DNSimple API v2 is now Generally Available
Simone Carletti
on
At DNSimple we truly believe in automation as a key goal for domain and infrastructure management. Today we are making a big step towards that goal with the general availability of the next generation of domain management APIs, the DNSimple API v2.
Redesigning our API has been one of the largest projects ever at DNSimple. API v2 is the result of a combined effort between several team members for almost two years. The very first API v2 ticket is dated December 2014, when we started the design process that eventually lead to the API v2 implementation.
API v2 has been in public beta since March 2016. During these 9 months of beta we invested lot of energy into improving the stability of the API. Even more importantly, we've been polishing responses and serialization details to make sure future enhancements could be introduced incrementally without majort breaking changes to our API. For you as a customer this means a stable platform that you can trust. You can safely integrate with and build your own domain and system automation on top of API v2.
Along with the general availability of our API, we also released the following API client versions:
Core values
For API v2 we had a few important design goals in mind:
- design a public API that is as independent as possible from our internal implementation
- decouple the API from the primary application to scale up independently
- expose a truly programming language independent API
- provide tools and features that facilitate integration with DNSimple
- provide a modern API for domain management automation
During the entire design, development, and testing process, we adopted simplicity as one of the leading drivers. Simplicity, without sacrificing features and usability.
We learned a lot from the mistakes we made designing (or not properly designing) previous API versions, and spent a lot of time discussing how every single endpoint fit in the global API v2 structure.
As part of the goal to facilitate the adoption of the DNSimple API, we also implemented 4 official API clients. Working in parallel with several different languages turned out to be a major source of inspiration for our API. We learned a lot about the implications of certain design decisions when it comes down to consume an API from certain programming languages; we dedicated a lot of time adjusting our response formats to facilitate API client development.
Developing official clients was also an extremely valuable dogfooding task. By acting at the same time as a producer and consumer, we could discover blocking issues early on in our development cycle and fix them, or provide practical guidance on how to properly interact with the API.
What's new
I already covered most of the new features in the API v2 public beta announcement, but I'd like to quickly summarize here the most important changes in API v2:
-
Official API clients: we now provide official API clients for Go, Ruby, Elixir, and Node.js. These 4 official API clients are maintained by DNSimple team members, and they implement ALL of the API methods currently available in API v2.
-
Multi-account support: API v2 fully supports the multi-account feature by allowing to specify the account as part of the API call. Account and User are a many-to-many association in DNSimple: you can create multiple accounts with a single user credential, likewise an account can be shared with several users. The DNSimple API v2 covers and properly supports both scenarios.
-
OAuth 2: API v2 implements authentication via OAuth 2. You can either create OAuth tokens manually from the application, or create an OAuth application and use OAuth web flow to integrate the DNSimple authentication system into your project.
-
Webhooks: API v2 provides webhooks for most of events that happens on your account. Each time an event occurs, such as a domain renewal, the DNSimple application will send a notification to your webhook URL with the event details so that you can trigger actions in your system based on events happening on the DNSimple platform.
-
Enhanced domain registration: API v2 supports several domain registration enhancements. For instance, you can now fetch the list of TLDs we support, along with each TLD setting. We also added support for domain premium pricing, introduced by registrars as part of the new gTLDs.
-
Advanced features: API v2 includes several long awaited features such as record pagination, consistent JSON serialization, consistent error handling, consistent date formatting, advanced sorting and filtering.
-
Documentation and examples: as part of our effort to simplify the adoption of our API, we wrote detailed API reference, documentation, and we also have example repositories we will feature in the coming weeks containing practical code examples in different languages. We also scheduled informative blog posts and tutorials, such as the one about Learning the DNSimple API by Bulding a CLI in Golang.
Behind the scenes
There's a lot of changes behind the scenes of the API v2. The whole API system was completely redesigned from scratch; we analyzed, designed, and re-implemented every single method.
The core DNSimple application is a large Ruby project. One of the major changes is that API v2 was developed on top of the Hanami Ruby web framework. This is probably one of the biggest, if not the biggest, project(s) using Hanami to date, and we are really happy with how it is performing thus far.
If you want to learn more about how we integrated Hanami into our current Rails stack, I gave a talk at RailsConf 2016 about Developing and maintaining a platform with Rails and Hanami, the full video recording is also available.
DNSimple will also be sponsoring the CodeMash conference on January 2017, where almost the entire team will be present and available to talk about the new API and upcoming projects.
The numbers
- a total of 717 days since we started the project. The first ticket was opened on December 28th, 2014.
- 3 (almost) full-time team members out of 11 total, with a collaborative effort from the entire DNSimple team
- 4 official API clients, with 2 more under development
- 75 API methods currently available
- 251 tickets across 7 major milestones
- ~423 API related support tickets handled in the last year
- ~1934 commits, across the 4 API clients and the server codebase
Roadmap
With the release of API v2, we are now officially deprecating API v1.
API v1 will be discontinued on October 1st, 2017. We understand that this may seem like aggressive planning, and we will actively work with existing customers and open source projects to facilitate the transition to API v2 as we did when we announced API v1.
API v1 was the first step towards a large redesign that resulted in API v2. The official Ruby client proved to play a key role in the update, as we could limit the impact of API changes by wrapping them as a responsibility of the client. By providing official clients our goal is to facilitate the transition of existing applications to API v2, and reduce the maintenance required to stay on top of API server changes.
API v2 currently covers all of the existing API v1 endpoints. However, there are still several features we don't expose in the API that are available in our application. In the coming weeks and months we will continue to improve our API and expose features such as the ability to request Let's Encrypt certificates, reverse zone support, as well as billing and other account-level settings.
All the new features that will be exposed via the API will be exposed via the official API clients as well.
API v1 future
API v1 will be discontinued on October 1st, 2017. After that date, it will no longer be possible to connect to API v1.
Starting from today, API v1 is officially in maintenance mode only. We will not introduce new features in the previous version of the API, although we will continue to apply security patches and patch issues with a large impact on our customers. Smaller issues may not be patched, if covered by API v2.
Getting started
Here's a few resource to get started with the new API v2:
- The main DNSimple domain management API, with links to the various resources and API clients
- The official developer reference
- A repository with various examples on how to use the API
Finally, we'd love to get your feedback on the new version of the API. If you are already using our API v1, or if you plan to use our API, please take the time to try API v2 and let us know what you think.
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.
