Semantic Documentation
I’ve been playing around a lot with API design lately because I have an API project coming up at Argu. But one of the things missing a lot from the design standpoints was one of the (in my opinion) most important aspects, the documentation. But before diving into that, there are some other conventions I came across, and since I’m used to Rails, I value conventions.
One of the most interesting things I came across is Semantic Versioning. Truly a great idea. Know what you’re up for, just by looking at the difference in version between the one you have and the one you want.
Something that also somewhat adheres to this convention is the URL. Not the path part, but the subdomain. If you see ‘www’, you’ll know it’s probably an html resource. Whenever you see ‘api’, you’ll be expecting some kind of JSON or XML response. Easy.
Finding the docs
A typical API is meant to be consumed by computers, therefore a lot of the focus goes (rightfully so) to the technical stuff like nested vs flat or the versioning debate. But before computers (or rather applications) consume them, humans are the ones who need to build the apps that consume the API, which in turn means that documentation discoverability is an important aspect of an API.
When looking into different API formatting standards, one (HAL) stood out for its documentation discoverability. Namely, it embeds a link to the relevant documentation in the response, but that comes with two distinct tradeoffs.
First, it requires the API to know the structure of the documentation, which doesn’t make for a very clean separation of concerns.
Second, we need to send close to a hundred bytes with every response, that isn’t a great option for a culture where byte-saving is a big deal.
Making it semantic
What if we’re able to find the docs for every API call without even needing a link? Now that’d be great, and it basically boils down to one sentence;
Change the API URL’s subdomain to ‘doc’
Easy isn’t it? Now we can always simply access API documentation whenever we run into unexpected behaviour. And it can help even more in the sense of documentation toolchaining. For example, a simple browser extension to track whenever you’re on an Semantic Docs enabled API and give you a pop-up. Or, for debugging why on earth you get that 400 response, going to the doc url while leaving the parameters in, the page can validate the request for you! (It should still show a heads-up about non-url parameters like auth headers, but form data can be appended to the url)
All in all, I’m going to try to do this on the next API I’ll create (I’ve got a nice open data project coming up) and see if it works as nice as advertised.
Let me know what you think in the comments!
