What does an API mean, and how do I use it?

An API is an "Application Programming Interface". It's a way for computer systems to send information back and forth. Namikoda uses an API to provide information about IP addresses

For more information, check the Wikipedia page or the excellent writeup that Mailchimp has.

API Keys

You can generate API keys at our management site. For a detailed set of instructions, see the registration page.

Code examples

How to use an API key to authenticate to Namikoda

Namikoda uses a single header to authenticate API calls. The header is X-Namikoda-Key. In order to authenticate each request, it must include an X-Namikoda-Key header with the value of an API key that was generated through our management site.

Getting the list of available IPs

Check out the list of sites on the sites available page.

Getting the IPs for a particular site

First, find the ID of the site you're interested in on the sites available page. Once you have the ID, put it in the URL and do a GET request to it. For example, the ID of github.com is github. It would be queried like this:

For OSX or Linux:

curl -H "X-Namikoda-Key: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" https://api.namikoda.com/v1/public/ipsfor/github  

For Windows, using PowerShell:

Invoke-RestMethod -Header @{ 'X-Namikoda-Key' = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' } 'https://api.namikoda.com/v1/public/ipsfor/github'  

SSL

We have a valid, signed certificate for all HTTP methods, and will only serve data over HTTPS. At Namikoda we are strongly in favor of SSL encrypted traffic everywhere. Make sure your network libraries support HTTPS, and be sure to enable it.

JSON vs XML

We support both, with JSON as our default. Put a header of "Accept: text/xml" if you want XML data back

For OSX or Linux:

curl -H "X-Namikoda-Key: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" -H "Accept: text/xml" https://api.namikoda.com/v1/public/ipsfor/github  

For Windows, using PowerShell:

Invoke-RestMethod -Header @{ 'X-Namikoda-Key' = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' } -Header @{ 'Accept' = 'text/xml' } 'https://api.namikoda.com/v1/public/ipsfor/github'  

What's new or different

We're currently on version 1. Updates to the API will appear in this space.

What can go wrong - error messages

401 - Unauthorized

You might see this error code if you try to access a URL that contains components that you don't have access to, or are misspelled. Be sure that your url starts with https://api.namikoda.com/v1/public/. The API will not return any data in this case.

You'll also see this error code if the value of the X-Namikoda-Key header is not a recognized and valid key. You'll also see the following output from the API endpoint

{ "httpCode":"401", "httpMessage":"Unauthorized", "moreInformation":"Client id not registered." }

Fix it by logging in to the management site and ensuring that the key you generated matches the key in your request.

404 - Not found

You'll see this if the ID of the site you are requesting does not exist in Namikoda. You'll see the following output from the API endpoint

{ "error":{ "statusCode":404, "name":"Error", "message":"Unknown \"ipsfor\" id \"something-unknown-here\"." } }

Check out the list of sites on the sites available page.