Features

Announcing DNSimple API v2 Beta

Simone Carletti on Mar 9, 2016

I'm super-uber-mega-very excited to announce that the new DNSimple API v2 is now available in Public Beta.

The DNSimple API v2 is not just a simple version bump, rather it is the result of two-and-a-half years of re-engineering and development.

The major features introduced with API v2 include: OAuth 2 authentication, multi-user account support, official clients, enhanced domain registration, pagination as well as a completely redesigned and more coherent user experience.

You can find more at the DNSimple API v2 documentation.

DNSimple API v2

OAuth 2

Authentication now fully supports OAuth 2 tokens. You can generate an access token manually from the DNSimple application, or programmatically using the OAuth web-flow. In the future we will add support for generating access tokens via other flows as well (for use in non-web applications, for example).

As a developer, you can also integrate your application with DNSimple and access account resources after being successfully authorized by a user. Simply register your application in DNSimple, and use the OAuth web-flow to get the user authorization to access his account information.

OAuth is the API v2 preferred authentication method because access tokens can easily be revoked and granted on a per-application basis. There are other authentication mechanisms available, such as HTTP Basic Auth. Users with two-factor authentication enabled will be required to pass the OTP token in the request when not using the OAuth token.

Multi-user support

Last year we introduced multi-account support into DNSimple. With multi-account support a DNSimple customer can have several accounts, for example a Personal account with private domains, and a Professional account for her company, shared with other team members.

API v2 fully supports multiple accounts per user and multi-user accounts:

you can generate an OAuth token for an account, and authenticate against a specific account regardless of users connected to it.
you can generate an OAuth token for a user and access any account connected to that particular user. You can switch between accounts simply passing the account ID in the API request.

The following two calls use the same token to access the list of domains from two different accounts:

# account 123
$ curl -X "Authorization: Bearer a1b2c3" -H "Accept: application/json" https://api.dnsimple.com/v2/123/domains
# account 456
$ curl -X "Authorization: Bearer a1b2c3" -H "Accept: application/json" https://api.dnsimple.com/v2/456/domains

Official clients for different languages: Ruby, Go, Elixir, …

One of the major goals of API v2 is to lower the effort required to build new integrations with the API. When we started planning the new version, we asked ourselves: what can we do to make it even easier for customers to use our API?

Several ideas came out from the discussion, but one of the most popular amongst the team was to expand our list of official clients. We have been providing an official DNSimple Ruby API client since 2010 (formerly known as dnsimple-ruby). The goal we set was to ship API v2 with not one, not two, but 3 official clients.

API v2 ships with 4 official clients: Ruby, Go, Elixir and PHP. The Ruby client and Go client are fully-featured and already implement all of the API calls currently available in the DNSimple API v2. The Elixir and PHP clients are works in progress, and our goal is to complete them by the time API v2 exits beta.

All of the clients were developed in parallel, with a specific goal: provide a consistent experience specifically for naming and method signatures. Even so, we've tried to follow the language conventions as much as possible to provide a native experience.

The choice of languages was made based on the current API usage, internal skills and knowledge. Our primary languages are (in order) Ruby, Go and Erlang, therefore the selection of clients should not surprise you.

We're definitely considering expanding our official API client list to cover other languages, such as C#, JavaScript and Python. Contributions are welcome. If you are interested in working on a client for a different language, we'd like to hear from you.

Enhanced domain registration

We've been supporting domain registration and transfer via API for quite a while, since we introduced them in the app 2010. In the last 6 years the domain industry has changed quite a while with the introduction of the new gTLDs and premium domains.

The domain registration and transfer API v2 has been completely redesigned to provide an enhanced domain registration experience. The domain check returns information about premium domains, it's possible to programmatically fetch the list of TLDs we support along with the specific TLD features. Registries have different rules and policies, and with the TLD API you can now easily determine whether a TLD supports — for example — the whois privacy.

Pagination and other features

API v2 includes several long awaited features such as record pagination, consistent JSON serialization, consistent error handling, advanced sorting and filtering. Some of these items are still works in progress, but they will be complete by the time API v2 reaches General Availability.

There are also a couple of more surprises we are working on that will be announced in the future. Stay tuned!

In the meantime, we encourage you to try our API v2 and send us your feedback.

Roadmap

The developer preview version of API v2 was released in December 2015 for internal testing, and opened to a limited set of private testers at that time as well.

The public beta starts today, and during the next weeks we'll continue working on the API, tweaking what we have according to your feedback, and integrating the missing pieces.

At this time the API is stable enough to be used, however please note that during the beta phase we may still make breaking changes. We'll do our best to communicate them in advance through the developer site and minimize the impact.

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.

Share on Twitter and Facebook