“I’ll just learn this new REST API by reading the comments on all the URLs” said no developer ever. But this is usually how we document our APIs. Is there a better way?
Good technical documentation is hard work, and don’t let anyone tell you otherwise. There is a real art to exposing the nuts and bolts of something as intricate as a software interface in a way that allows those consuming it to get up and running with a minimum of frustration.
The newly released Spring REST Docs project is one attempt to redefine how developers think about good documentation. There is a great presentation that explains some of the ideas behind this project, and I definitely recommend anyone interested in improving the developer experience of their RESTful APIs take the time to watch it.
The one aspect of this project that really stood out for me was the move away from documenting URLs. It stood out mostly because this is something I have done in the past myself, but also because I have had to consume documentation that was centered around the URL structure of an API, and it wasn’t a great experience.
Let’s say that I, as a developer, need to update the name field on a user via an API. This sounds simple enough, but in practice there are plenty of unknowns when performing even this simple action against a standard RESTful API. A few examples might be:
Do I need to first get some kind of access token or provide authentication details?
What permissions do I need to do this update?
What are the validation constraints that need to be met by the new value for this field?
What error codes do I need to deal with in the case of errors?
Is this a PUT or a PATCH operation?
With documentation that is focused around URLs, you might end up looking at something like this:
To get from “I need to update the name field on a user” to this particular entry in the API docs, you are forced to make some assumptions.
You need to know that the HTTP PUT verb is usually the one you use for an update, and you have to assume that the lack of a HTTP PATCH verb in any other endpoint indicates that this API has indeed implemented PUT as the means by which resources are updated.
You can see that the body is expected to be a JSON object, and the field called firstname is most likely the one you need to define. Maybe you can send this field on its own, but maybe you can’t. You're forced to use trial and error to see exactly what you need to send to this endpoint in order to update the one field you am interested in.
The implementation notes state that you need to be logged in before you can call this particular end point. But how do you log in? Is it BASIC authentication, or do you retrieve some kind of token with an additional API call?
For such a simple task as “I need to update the name field on a user”, this URL focused documentation has already forced you to deduce the HTTP verbs that you need to work with, run some trial and error queries to find out if you can update fields in isolation, and jump to some other part of the documentation to learn how authentication works.
You’ll know poorly designed documentation when you see it, because for every answer you get, you’ll have three more questions. With poorly designed documentation, bridging the cognitive gap between what you know, what the documentation assumes you know, and what you need to learn involves a lot of effort.
Compare that experience to the one you get with something like the GitHub API Docs. Right off the bat you see links to documentation that details what HTTP verbs are used by the API, how authentication works, and answers to almost every other question you could have about the common functionality of this API. Once you have familiarised myself with these practical details, you can jump into the specific operations that have been exposed on the individual entities.
You’ll know good documentation when you see it, because for every question you have, the answer is right there. The documentation effortlessly steps you through the process of moving from what you already know to what you need to learn, and makes very few assumptions.
So next time you are documenting your API, take a moment to think about the developer experience. Will you provide the information that a new developer would need to get started with your API, or will you assume that they can just work it out from a list of URLs with some comments? That decision might be more important than you realise.