5 things you need to fix in your API documentation

Any adult recognizes in a blink of an eye which is which by the shape and color of a beer 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.

This thinking process and instant recognition is part of the developer experience, which is an often (mis)used term. A single API or a software development kit (SDK) can create a good or bad developer experience. When we talk about onboarding developers as new API consumers, we have to talk about the customer and user experience of those developers. This is often included in the term developer experience when talking about APIs.

• What are their expectations of how the APIs work?
• How do they get access to the API?
• Should they pay for the API or get it free, at least for trying it out?
• What kind of examples, documentation, layout, and content do they expect, and what channels do they expect to find your API?

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.

‍

‍Pre-purchase touchpoints are where the developer understands she has a specific need. This can be something functional, like face recognition or calculating shipping costs. It can also be about accessing data like mapping street addresses with postal codes. The developer then starts looking for internal or external solutions. 

Remember, she always has the option of implementing the necessary feature herself. As in any customer journey, the thing to understand is the impact of the developer customer’s previous experience. This can include experience using other APIs or other services. These past experiences will affect how they perceive your APIs.

When the developer moves forward in the journey, she needs a way to try out the API. With APIs, like any software product, it's essential to try them out before buying. Keep questions to the bare minimum before they can try at least a minimal set of features with the API.

The post-purchase touchpoints are critical, like getting support and advocating about the API. Understand the channels and the ways for the developers to get assistance using the API. No matter what you decide to offer them as support channels, they might look for support elsewhere. The developer might be searching the web or listening to their favorite YouTubers. She may ask a question from peers in Stackoverflow, Gitter, Reddit, or Discord.

If all ends well, and the developer solves their coding problem using your API, they may be your best advocates. They might even make tutorials, videos, helpful code libraries, or use your API to train others. They might answer other developers' questions about your API in some community support forums and reduce your support load.

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.

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?

Wrong.

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).‍

4. 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.

‍

5. Validate your schema - all of it

If you design and publish your APIs with OpenAPI, and you should, make sure you validate both the JSON, XML or YAML but most importantly, validate the OpenAPI definition file it self, too. And your examples. Developers are not able to use any tools or libraries directly to use the API, if it isn't valid.

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