Adopting OpenAPI to describe DNSimple API v2
Anthony Eden
on
In October last year, Simone spoke at API Strat, a conference about API development and adoption. This conference was jointly hosted by The Linux Foundation and the Open API Initiative. After the conference we were intrigued by the OpenAPI 3 specification and how it might help us define and document our API better. This came in conjunction with a desire by the team to improve the DNSimple API documentation. Here's a bit about the journey from zero to a complete Open API specification file for the DNSimple API.
The Problem
The DNSimple API offers quite a bit of functionality for managing your domains, registering and transferring domain names, acquiring SSL certificates, and more. Up until now, we've implemented the DNSimple documentation by hand, keeping the documentation in sync by updating it each time we release API endpoint updates. This has worked reasonably well for us, but there are gaps in the documentation. For example, parameters that are accepted by the API are not always clearly documented, nor are the return structures. Webhooks were also an area where we missed documenting some of the newer events as our list of supported webhook events has grown.
Another problem we face is supporting multiple API clients in parallel. We have a number of official API v2 clients: in ruby, go, elixir, javascript, and soon java. Each one of these clients must be updated everytime a new endpoint is added, or an existing endpoint is updated. While we love practicing our chops on different languages, it does consume a lot of time to maintain each client implementation.
The Solution
OpenAPI offers a means to define our entire API, including webhook callbacks, in YAML and/or JSON. We opted to develop our OpenAPI document in YAML and then generate the JSON. I started the implementation by defining our existing endpoints, as well as each of the request and response data structures.
On the tooling side, after trying several different editors, we ended up using Swagger Editor, which is a Node web application. The workflow we selected was to run Swagger locally, importing our openapi.yml file into the application whenever we want to edit it and then to export it back out when we're done working on it. The openapi.yml file is then checked into our developer documentation repository. Whenever that repository is published to GitHub Pages, the openapi.json version of the document is generated.
The most significant benefit to the Swagger editor is that it verifies the structure of the OpenAPI document in real-time, calling out any errors. Regardless if you are just starting out or you've been working with OpenAPI for some time, having real-time structure validation is a huge help.
Another benefit is that implementing OpenAPI forced us to consider our API implementation, the inputs and outputs, and whether or not various parts of our system are clear, concise, and easy to understand. Even if our code is stable and well documented, if there are design issues with the API itself, it is sometimes hard to see this without a single broad view of the system. An OpenAPI document helps bring the whole picture of the API into focus, while still permitting drill-down into subsections of the API.
Eventually, we also hope to take advantage of the automatic client generation tools that are available. We hope that these tools will allow us to bring even more API clients to customers at a much faster rate.
Finally, the one other piece of OpenAPI we want to take advantage of is the automatic documentation generation. While working on the OpenAPI document we discovered gaps in our documentation. We think that by moving the documentation over to generated documentation, we should be able to close those gaps.
The Issues
Last year the Open API definition had a significant overhaul, moving from version 2 to version 3. Most of the tooling is not yet updated to version 3, making development a bit more difficult than we initially expected. As described above, I fought with several different editors as part of the process of developing the initial OpenAPI document, including commercial offerings. Unfortunately, none of them worked particularly well, with Swagger being the only version that consistently caught all of the various issues in the OpenAPI document. This isn't very surprising given the connection between Swagger and OpenAPI: the OpenAPI specification was born from the early Swagger implementations.
Given that we started shortly after the release of OpenAPI, I had to reach back to the OpenAPI specification as the source of truth, and at times the document lacked clarity. Again, real-time updates in the Swagger editor, along with a lot of tweaking of our OpenAPI document, helped us better understand some of the more cutting-edge pieces of the OpenAPI specification, such as the callback section.
Conclusion
I believe that OpenAPI has the potential to simplify several tedious parts of API development, including client implementations across various platforms, as well as documentation generation. After a bit of experimentation, and through the solid feedback of the Swagger editor, I feel we've reached a good starting point with our OpenAPI document. In case you're interested in seeing what it looks like, we've published it on the DNSimple Developer site in JSON format. Take a look and see what you think.
If you're interested in seeing a follow-up article or two about the actual implementation details of our OpenAPI document, including with code snippets explained, just let us know by contacting us or by commenting on Twitter, where we are @dnsimple.
Anthony Eden
I break things so Simone continues to have plenty to do. I occasionally have useful ideas, like building a domain and DNS provider that doesn't suck.
We think domain management should be easy.
That's why we continue building DNSimple.
