First look at Digital Ocean's new API

Digital Ocean was built with developers in mind. With low prices, high performance virtual machines and a simple and straightforward interface, it has managed to attract many freelancers, startups and SMBs.

Especially the web interface really shines in comparison to competion. However this is not the only way a developer will interact with a cloud provider. Digital Ocean's API, though available from early on, came with some caveats. Fortunately, a few months ago, DO launched a beta version of their new API, which aims to solve most of these issues, while adding new functionality like oAuth authentication and support for IPv6.

A RESTful API makes much more sense

Certain tasks in the first version felt a little awkward. Lets look for example at key management:

Function	Type of request	Command sent
Create a new key	GET	/ssh_keys/new/
List all keys	GET	/ssh_keys
Destroy a key	GET	/ssh_keys/key_id/destroy/

It just seems unnatural and quite difficult to remember, forcing you to check the documentation all the time. However, the new beta version is truly RESTful, which makes things much simpler:

Function	Type of request	Command sent
Create a new key	POST	/account/keys
List all keys	GET	/account/keys
Destroy a key	DELETE	/account/keys/key_id

Easier to remember and pretty much what you would expect once you start working with the API.

Improved Authentication

OAuth support was also a much welcomed addition. It allows developers to authenticate with DO using third-party services like Github. Also, services and apps built around the DO API can now share credentials with the DO account.

More importantly, users can create and authorize API tokens to provide read-only or read/write access to their account without exposing their credentials. Having your read-only API token compromised can result in much less frustration and damage than having your credentials stolen.

Better key management

The are also several issues fixed in the new version. For example, asking for a list of your ssh keys through the old API, returned a list with ids and names, but without the public keys. That made it impossible to tell if a key you had locally, already existed in the DO account. Furthermore, if you tried to upload a key that already existed, the API returned an unspecified error with no info on why the key failed to get imported (was it a bad/unsupported key or did the key already existed in the database?):

{u'error_message': u'SSH Key failed to be created',
u'message': u'SSH Key failed to be created',
u'status': u'ERROR'}

In the latest version, you get a proper response with much more info:

{u'message': u'Ssh key SSH Key is already in use on your account', u'id': u'unprocessable_entity'}

Conclusion

Although still in public beta, the new API is already a big improvement compared to the first version. There is an open tracker if you are having issues or if you want to ask for a new feature, and as always, the Digital Ocean community is very active in writing documentation and providing help. Most of the tools using the API are migrating or have already migrated to the new version, although we expect that the old version will still be around for some time.

The new API is very well documented and with many examples provided. Overall, we think that Digital Ocean did a great job on the new version and solved some long standing issues while creating a modern, easy to use API. Well done!

We have already switched to using the new API and we've been quite happy with it so far.

Are you using Digital Ocean? Mist.io can help you manage and monitor your virtual machines from anywhere. Try it for free.