Deconstructed HTTP API documentation

Florian Klauer

1. Documentation usability
2. Bad API documentation
3. Deconstructed HTTP API docs ←
4. API documentation mistakes

Developers write bad API documentation because they apply good coding habits to technical writing, where they don’t belong. In particular, software development encourages aggressive hierarchical decomposition - putting things in boxes.

Putting things in boxes

‘Divide and conquer’ (Latin: divide et impera), the fundamental maxim of software development, dictates that every detail of a system must exist inside some kind of ‘container’. This approach deals with essential system complexity by adding as much accidental complexity as possible. This also has the benefit of introducing endless new container abstractions, to maximise the work of naming things.

While I might not actually mean that seriously, it does seem that every era and branch of software development has its own container fetish. This explains why technology stacks use so many synonyms of container: repository, cache, archive, stash, file, folder, envelope, wrapper, directory, catalogue, module, package, bundle, crate, batch, etc. And despite these abstractions’ value, software developers sometimes go too far.

Deconstructed interactions

The small phrasebook Making Friends in English (Penguin Quick Guides) contains this brief example dialogue that takes place at a party (original emphasis):

MARK: Raúl, come with me and I’ll introduce you to a few people.

RAUL: OK.

MARK: Have you met Lucy?

LUCY: Yes, we’ve already met.

MARK: OK, in that case, meet Sam. Sam and I were at college together. Sam, this is Raúl. Raúl’s a mate of mine from Spain.

If you wrote this phrase book the way developers usually write API documentation, you’d end up with something like this:

In the pursuit of abstraction, deconstructing the introduction has discarded the conversation, leaving information without context or explanation. You can’t use this to understand how the introduction works. HTTP API documentation typically suffers the same fate.

Deconstructing an HTTP API documents the wrong API

HTTP API documentation tends to structure the API in a deeply-nested hierarchy:

Base URL
┣ URL path
┃┣ HTTP method
┃┃┣ Request
┃┃┃┣ Parameters
┃┃┃┣ Headers
┃┃┃┗ Body
┃┃┣ Response
┃┃┃┣ Status
┃┃┃┣ Headers
┃┃┃┗ Body
┃┃┗ Errors
┃┃ ┗ …
┃┣ …
┣ …

Splitting each HTTP request across this hierarchy scatters the parts of a URL like https://api.example.com/search?query=new to several different places in the documentation. Extracting duplication, such as authentication and errors, from requests and responses by moving the information to a single place in the documentation, somewhere else, makes the situation even worse.

HTTP API documentation that removes all duplication overfits to a particular abstraction - a way of thinking about that API that has more to do with how you might implement the same functionality in, say, an object-oriented programming language. The documentation essentially documents that other API, not the HTTP API.

API treasure hunt

The documentation’s author might find the resulting structure exceedingly satisfying, but its appalling usability will frustrate readers, who have to assemble API requests by playing a perverse game of treasure hunt.

Instead, HTTP documentation should look more like HTTP itself, and should at least present the information that goes together in an HTTP request in the same place. After all, HTTP’s request-response style makes an HTTP API a conversational API that has more to do with Raúl meeting Lucy at a party than objects and functions in code.