Free Trial

Announcing the Versioned API

Simone Carletti's profile picture Simone Carletti on

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 domain to 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<path>

should now be performed to<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

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' \

in v1 becomes

curl  -H 'X-DNSimple-Token: <email>:<token>' \
      -H 'Accept: application/json' \

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 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>' \

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.

Testing the API in the 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 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 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's profile picture

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.

We think domain management should be easy.
That's why we continue building DNSimple.

Try us free for 30 days
4.5 stars

4.3 out of 5 stars.

Based on and reviews.