Overview

This page provides an overview of the official DNSimple API v2.


URL

All API access is over HTTPS, and accessed from the api.dnsimple.com domain.

In order to maintain compatibility in the future, all requests must specify an API version, which is appended to the URL.

https://api.dnsimple.com/v2/

Testing

We maintain a separate environment for testing called Sandbox accounts. Sandbox API calls must use the api.sandbox.dnsimple.com domain.

Please use Sandbox for testing your API integration, before using production. Also note we will not refund you charges on your production account as a result of wrong API calls.

Current Version

The current API version is v2.

Authentication

There two ways to authenticate through DNSimple API: the HTTP Basic Authentication and the OAuth2 token.

When you create an OAuth2 token programmatically, the token is scoped to the specific account granted during the OAuth2 dance. When you create an OAuth2 token from the application, you can create either a user token or an account token. The user token gives you access to any resource associated to any account the user has access to. Conversely, an account token gives you access only to the resources connected to that account.

The HTTP Basic Authentication always authenticate you as a user.

HTTP Basic Authentication
curl -u 'EMAIL:PASSWORD' https://api.dnsimple.com/v2/whoami

Users with two-factor authentication enabled must send an extra HTTP header for the request.

curl -u 'EMAIL:PASSWORD' -H "X-Dnsimple-OTP: 2FA-TOKEN" https://api.dnsimple.com/v2/whoami

In case two-factor authentication is enabled but the header is not sent, the application will respond with a 401 and a response header: X-Dnsimple-OTP: required.

OAuth2 Token
curl -H 'Authorization: Bearer OAUTH-TOKEN' https://api.dnsimple.com/v2/whoami

Note that Oauth2 tokens can be acquired programmatically and via OAuth dance or can be generated from the user/account sections in the DNSimple application.

Response Codes

DNSimple uses conventional HTTP response codes to indicate success or failure of an API request.

Successful

  • 200 OK - Everything worked as expected.
  • 201 Created - The request was successful and a resource was created. This is typically a response from a POST request to create a resource, such as the registration of a Domain or the creation of a Contact.
  • 202 Accepted - The request has been accepted for processing. This is typically a response from a POST request that is handled async in our system, such as a Domain transfer request.
  • 204 No Content - The request was successful but the response body is empty. This is typically a response from a DELETE request to delete a resource.

Error

  • 400 Bad Request - A required parameter or the request is invalid.
  • 401 Unauthorized - The authentication credentials are invalid.
  • 402 Payment Required - Your account is not subscribed or not in good standing.
  • 404 Not Found - The requested resource doesn’t exist.
  • 429 Too Many Requests - You exceeded the allowed number of requests per hour and your request has temporarily been throttled.

Kaboom!

  • 500, 502, 503, 504 Server errors - something went wrong on DNSimple’s end.

Responses

All successful responses will be returned as a JSON object with at least one key: data.

The data element will contain either a single JSON object or a list of JSON objects, depending on the endpoint.

{
  "data": {
    "id": 1,
    "first_name": "Jane",
    "last_name": "Smith"
  }
}

Errors

Error responses will be returned as a JSON object with at least a message key. For example, failure to authenticate would result in a 401 response with a body like this:

{"message":"Authentication failed"}

Timestamps

All the timestamps and the dates are formatted according the ISO-8601 standard.

2016-12-11T17:31:51Z # Timestamp
2016-12-11           # Date

Account scope

The majority of API methods are designed to be executed within the scope of a specific account. In this documentation, the account parameter is identified by the :account string in the API method path:

# An example of the API method to list the domains
# for a specific account
GET /:account/domains

The account identifier must be supplied regardless the authentication mechanism, even if you use an account token. Remember that an account token limits the permission to a specific account, whereas an user token allows to access any resource on any account associated with the user.

The account identifier is represented by a numerical account ID. You can obtain the account identifier either programmatically or manually.

Getting the ID manually from the URL

URLs in the main DNSimple application are also account scoped, the account ID can be reused in the API calls. To get the account ID, log into DNSimple, click on the account switch on the top-right of any DNSimple page, select the relevant account. Once selected, you will be sent to a page that contains an ID in the URL, for example:

https://dnsimple.com/a/1234/domains

The digit after the /a in the path is the ID of the account. In this specific example, the account identifier is 1234.

Getting the ID programmatically with an Account access token

If you use an account token and you want to get the ID programmatically, the simplest way is to perform a whoami API call. The response will contain the account identifier as part of the account payload.

{
  "data": {
    "user": null,
    "account": {
      "id": 1,
      "email": "example-account@example.com"
    }
  }
}
Getting the ID programmatically with a User access token

If you use an user token and you want to get the ID programmatically, you need to fetch the list of all the accounts associated with the user executing a listAccounts API call.

{
  "data": [
    {
      "id": 123,
      "email": "john@example.com",
      "plan_identifier": "dnsimple-personal",
      "created_at": "2011-09-11T17:15:58Z",
      "updated_at": "2016-06-03T15:02:26Z"
    },
    {
      "id": 456,
      "email": "ops@company.com",
      "plan_identifier": "dnsimple-professional",
      "created_at": "2012-03-16T16:02:54Z",
      "updated_at": "2016-06-14T11:23:16Z"
    }
  ]
}

The response contains one or more accounts. Select the relevant account based on a known criteria (e.g. the name or an user input), and get the corresponding ID.

Pagination

Any API endpoint that returns a list of items requires pagination. By default we will return 30 records from any listing endpoint.

If an API endpoint returns a list of items, then it will include a pagination object that contains pagination information.

The pagination object contains the following details:

  • current_page: The page currently returned (default: 1)
  • per_page: The number of entries returned per page (default: 30)
  • total_entries: The total number of entries available in the entire collection
  • total_pages: The total number of pages available given the current per_page value

For example:

{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith"
    },
    {
      "id": 3,
      "first_name": "John",
      "last_name": "Smith",
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 30,
    "total_entries": 2,
    "total_pages": 1
  }
}

You may include the following arguments as query parameters when you call an API endpoint that supports pagination:

  • page: The page to return (default: 1)
  • per_page: The number of entries to return per page (default: 30, maximum: 100)

For example:

https://api.dnsimple.com/v2/1010/domains?per_page=100&page=2

Filtering

Filtering makes it possible to ask only for the exact subset of data that you you’re looking for.

With potential hundreds of result entries, it’s covenient to apply a filter and receive only the interesting data.

API v2 supports this feature via query string.

Example

List all domains in the account 1010 that have name matching "example":

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/domains?name_like=example

Please have a look at the documentation of each endpoint to know about the filters it supports.

Sorting

API v2 results are implicitly sorted according to policies that vary from endpoint to endpoint.

You can decide your own sorting policy for each single API call via the sort parameter.

This parameter accepts a set of comma separated key-value pairs: the name of a field and the order criteria (asc for ascending and desc for descending).

The order of fields is relevant, as it will determine the priority of the sorting policies.

Example

List all domains in the account 1010 sorting them by expiration date (asc) and id (desc)

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/domains?sort=expires_on:asc,id:desc

Rate limiting

There is a limit to the number of requests that you can perform per hour.

  • For authenticated requests you can make up to 2400 requests per hour.
  • For unauthenticated requests, you can make up to 30 requests per hour.

You can see your current rate limit status by checking the HTTP headers of any API request:

$ curl -H "Authorization: Bearer ACCESS-TOKEN" -I "https://api.dnsimple.com/v2/whoami"

HTTP/1.1 200 OK
Date: Fri, 11 Dec 2015 11:15:42 GMT
Status: 200 OK
Connection: close
X-RateLimit-Limit: 2400
X-RateLimit-Remaining: 2399
X-RateLimit-Reset: 1449836141

The headers have all the information you need to know about your current rate limit status:

Header Description
X-RateLimit-Limit The maximum number of requests you can perform per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window in Unix time format.

Once you go over the rate limit you will receive an error response:

$ curl -H "Authorization: Bearer ACCESS-TOKEN" -I "https://api.dnsimple.com/v2/whoami"

HTTP/1.1 429 Too Many Requests
X-Ratelimit-Limit: 2400
X-Ratelimit-Remaining: 0
X-RateLimit-Reset: 1449836141
Content-Type: application/json; charset=utf-8
Content-Length: 28

{"message":"quota exceeded"}

More Examples

You can learn more about interacting with the API through the DNSimple API Examples repository on GitHub. This repository holds examples in various programming languages that can help guide you through using the API.

Additionally, you can find various example web applications in the DNSimple organization on GitHub that will guide you through the creation of a basic web application that connects to the DNSimple API, obtains an OAuth token, and lists domains.