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
should now be performed to
For documentation purpose, we're officially referencing the existing API as
v0 and the new API as
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' \ https://dnsimple.com/domains/example.com
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.
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
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.