5 things you need to fix in your API documentation

September 7, 2019
Marjukka Niinioja

It was a good thing there was a bar at the party after the first day of NordicAPIs Platform Summit 2018 in Stockholm. After token validation (the beer tickets were in text messages), I needed a bottle of beer. Ok, I was thirsty, too. I needed the bottle to demonstrate my point to Ted Epstein on UX design for API documentation. I had talked about this in my talk earlier in the day a bit but now we got into deeper discussion. Ted had read my blog on “How to get more API users?” and had some great questions on it, particularly my statement of “Your site must not be pretty”.

So, I hijacked the bar and pointed out the beer, soda and wine bottles. Any adult recognizes in a blink of an eye which is which by the shape and color of the bottle. That’s how long an experienced developer needs to decide if your API documentation is worth it. Is it technical enough? Is it even an API documentation or some sales page? Blink. Move on.

I’m baffled by how UX people thinking that Developer experience isn’t a thing. I’m not the only one, though. Of course, deep down they are correct. It’s just that Developer Experience describes needs by typical developers using APIs, SDKs or other developer tooling. Developer Experience is not just User Experience, it’s also Customer Experience, again for that specific segment. And most of all, the implications for designing interfaces are different. It’s not only the website containing documentation, or the tools they use to code or make API requests. It’s about how to design the technical interfaces, for example APIs (Application Programming Interfaces). Those interfaces are not (just) designed for people, but also for optimal use by software, computing and network devices.

I would agree if many who practice UX weren't so tightly tied to the UI of the product offering on hand. Strip away the documentation, the portal, the registration flow and they're lost when the product becomes http statements over the wire. But DX still applies there.— 𝕞𝕒𝕥𝕥𝕙𝕖𝕨 𝕣𝕖𝕚𝕟𝕓𝕠𝕝𝕕 (@libel_vox) October 23, 2018.

Even developers are not a single identical group. Their expectations vary depending on who they are. Junior vs senior, front-end vs. backend vs. integration and programming languages and tools they use. And of course, developers are not the only group of users you need to talk about your API or SDK.

Developers try, business buys - Jason Harmon, Typeform, NordicAPIs Platform Summit 2018

Let’s move on the 5 things you need to change in your documentation:

1. What does your API do?

This should be obvious from the first title and sentence on your API documentation. And for each endpoint. Make sure it’s written for your target audience. The worst I’ve seen is “Search API: Search API is used to do searches”. Ok, but to search what? Why? Are there limitations or special combinations? If it’s an API in a developer portal containing public, partner and private APIs then who is this API for? Or could it you open it for everyone? This is something you would need to think about already when designing the API.

Wrong purpose, terrible API - Arnaud Lauret, API Handyman, NordicAPIs Platform Summit 2018

This is also the starting point in the creative-commons licensed APIOps Cycles -method  for API development. It all starts from the API Value Proposition.

2. Stop with the sequence diagrams, explain your product

Do you think developers know what your actual product or service does for what they are using the API for? Your product or service may need specific knowledge. Like accounting software, payment service or transcription service. If you don’t understand how that works, it’s hardly possible to understand what the API does.

You might be tempted to put flow charts or sequence diagrams in your API documentation. This usually happens, if someone has done diagrams while developing the API. Because a picture tells more than a thousand words, right?


Those diagrams that are often drawn from internal perspective. And they are missing the user flow of your product. If you have 10 different endpoints for your API, the external developer will most likely need a process diagram. It should show typical flow to use your product or accomplish a specific task in the product. As a bonus also what endpoints are needed. Clarify this in 1-5 simple bullet points as a list. If you can’t, then maybe consider simplifying the actual product?

3. Less words, better API

Now take out a tape measure. At least copy your text to Word or other processor which shows you the word count of your API documentation. If you have over 300 words of prose, be a bit concerned. Look at your text. Is it something like this: “You should use secure connections when calling our API…”?

If you need to write all this in sentences, it’s a sign you may have to redirect.

1) you have hired a “non-API” technical writer to do your API documentation., or

2) your API users are stumbling on the same problems or causing you trouble. What you should do is fix the API or use API management (see next item).

Please, kind Sir, don’t crash my API

Stop pleading: “Please do not make too many calls to our API, at least not during business hours”. If someone can crash your API by doing their calls whenever they want to, they will. Not because they are not very friendly. Because someone makes a coding mistake somewhere and spams your API by accident. Once an elderly lady put her coffee mug on top of the keyboard. She managed to crash a whole SaaS -application with it by making too many calls. Bad people will try to crash your API. What you say is that you have nothing to stop them, at least from slowing your application down.

One critical advice: put at least hard maximum rate limit to your API (per minute and user) and a smart standard error message.

Ok, this was only the top 5 things. Typically, we go through up to 20 things in our list to review your API and documentation.

Read more about the topic

Discover our latest news & best practises.

Let's stay in touch!

We won't spam you - we'll send you relevant content maximum 1-2 times a month.