Announcing the Versioned API

In the last year we've been working hard to consolidate our existing API and improve our API documentation. We're happy with the feedback we have received so far. More customers have been hacking with our API, creating new libraries and tools.

Today we're marking an important milestone in our API development. We're officially announcing a new versioned API and a new dedicated API base URI. These changes set the foundation for scaling and evolving our API in the future.

What does this mean in practice?

We've moved our API from the current dnsimple.com domain to api.dnsimple.com. From this point forward the API will be versioned using a path based versioning system.

We started versioning the API using v1 thus any API call that was previously performed to

dnsimple.com/<path>

should now be performed to

api.dnsimple.com/v1/<path>

For documentation purpose, we're officially referencing the existing API as v0 and the new API as v1.

For the sandbox site the new base URI is api.sandbox.dnsimple.com.

What are the differences between v0 and v1?

From a client-side point of view, there are absolutely no differences, except for the base URI. Every method available in v0 is available in v1, it accepts exactly the same parameters and it returns exactly the same response.

We decided to not make any changes on purpose. This is to facilitate migration of existing libraries and scripts (i.e. no additional effort and no compatibility issues).

For example, the following v0 API call

curl  -H 'X-DNSimple-Token: <email>:<token>' \
      -H 'Accept: application/json' \
      https://dnsimple.com/domains/example.com

in v1 becomes

curl  -H 'X-DNSimple-Token: <email>:<token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v1/domains/example.com

So why is it better?

Using a dedicated hostname for our API will help us to provide a better experience.

First of all, performing an HTTP call to the new api.dnsimple.com hostname will default the response content type to JSON. This means the example above could be simplified to

curl  -H 'X-DNSimple-Token: <email>:<token>' \
      https://api.dnsimple.com/v1/domains/example.com

Please note that we encourage you to keep passing the Accept header since this is handy for debugging.

Second, you can now debug an API call directly from a browser.

Finally, without going into too much technical detail the new versioned API also provides an improved error response experience. We can now unequivocally identify an API request and work around a known issue where, in some cases, we are returning an HTML response as a result to a failed API call.

Legacy API Roadmap and End of Life

With the new API available, we're deprecating the v0 API and the legacy dnsimple.com hostname for API calls.

v0 and v1 will run in parallel until June 30th to facilitate the transition to the new API. After that date, we'll stop supporting v0 and we will remove the ability to perform API calls to the dnsimple.com hostname.

What's next

The new versioned API will allow us to evolve our API with new features and changes without effecting compatibility of existing implementations.

We're planning to deploy a v2 of our API at some point (potentially before the end of the year). This version will include changes we've been planning for a long time. It will also include new features we've implemented after listening to your feedback.

Our API documentation has been updated to reflect this announcement. We've already released an update to our Ruby Client, if you are using it simply install the latest version to take advantage of the new API.

Happy coding!

Share on Twitter and Facebook

Simone Carletti

Italian software developer, a PADI scuba instructor and a former professional sommelier. I make awesome code and troll Anthony for fun and profit.