Intro

Many API documentation approaches exist in the industry. You can use many tools to automate creating the documentation: from XML-based comments and aggregators to Swagger API, Open API, etc. But I’m going to take a step back and share some tips that work for any specific approach or toolset you choose to create Public API documentation.

Why am I talking about it at all? Well, because I’m a software developer playing both roles of an API consumer and API producer. Throughout the last eight years (while working on several projects and in different companies), I’ve been integrating successfully with about ~100 various enterprise-level financial, travel, and geospatial APIs. I’ve seen many different ways to explain an API:

• 5 PDF’s 200-pages, each presenting a broad set of interdependent APIs.
• 3 sentences of explanation in chat.
• Dynamic web site requiring its own set of permissions and kind of internal wikipedia covering all of those deeps.
• Automatically generated documentation based on XML comments, JSON-schema, whatever…

Neither worked well. I also develop an API myself, and I know it’s not that easy to think from the customer or any external reviewer perspective.

But I’m assuming that you:

• Want your API to be useful and broadly used
• Want to have less burden answering simple questions
• Want to show how serious you and your solution is
• And you are going to maintain and extend your API in the following several years.

So, some guidance on what to keep in mind might help you. That’s why I want to shine some light on what’s important from your API customer perspective and how usual third-party developers will read your documentation and what he’s expecting to see.

Knowing this (and learning the skill of putting yourself in customer’ place) can help you show yourself as an expert, leverage benefits provided by your API, and decrease maintenance costs. And sometimes, it can let you find an issue or vulnerability in your API and fix it in advance.

Some of my recommendations may sound obvious, but it still plays an important role.

First things first — remember the goal

The one who is going to use your API doesn’t need to become an expert in it.

API customer needs to solve HIS TASK, not yours. Boom.

As a developer, I always had a particular request that needs to be satisfied using specific API integration. For example, I might need to make initial authentication to the service and show its page, thus providing the end-user functionality. Or, I should use some specific part of API functionality, but not the whole API.

In other words, people who will use your API are looking to solve their problems that might not be solved by your API at all or can be solved only in the specific scenario.

The documentation’s primary goal is to explain to your customer why to use your API and how to solve his problem by using it.

Format

The format itself doesn’t matter that much. In other words, you can fail at any of those. What matters is how many TIME I SPENT on reading and understanding the basics of the API. It might be a website page, a PDF, an interactive tool, or a combination of all three.

The clarity, navigation, and brevity make much more sense.

Follow the tips on it below.

First three pages

Vendor name

Don’t skip this part if you work at the enterprise. Companies buy each other. So, one day it can be MyAPI version 0.0.1 beta, but another day it will become GiantSoft API version 11.

Even if you are not an enterprise, but you treat your API as a product, it should have a straightforward way to name it.

Version

You can skip version of the API only if it depends on other products and its versioning or if it’s something very standard to the industry, for example, an integration through a well-known SAML protocol.

If your API is a product itself or there is any chance to be used by more than one person (I assume this is in most cases), you should stick to Semantic Version since the first 0.0.1 version of the API because it will be tough to change afterward. Here are a good example from Microsoft: https://docs.microsoft.com/en-us/dotnet/core/versions/.

Present the version of your API on the first page. Add a short explanation of how you expect it to be changed and updated. If it’s industry known standard (like Semantic versioning) — just put a reference link to it.

Table of content

Sounds obvious. But 50% of documentation doesn’t have it. Developers go straight to the description of API request/response. Maybe it’s not that bad for the simple API; however, in API with more than one method, your customer should understand what is essential to read and what’s not. API customer will not become an API expert, don’t expect somebody will read your documentation from A to Z.

First of all, your documentation should dive into details where needed and not from the first page. People are looking for some solution to the problem. The developer will frequently do a high-level review first to ensure that no significant blockers exist before the integration.

Thus, documentation should provide a structural approach and split into steps, phases, or examples that can be reviewed and selected appropriately to the needs.

Ideally, every step or phase should explain what you are going to achieve after finishing it.

As a customer of your API, I should select what parts of the API are essential to me.

Version history

There is a technique called Change Log in the open-source. It would be best if you had a similar thing in your API documentation. It may not need to describe every detail, but it should let your customer know what version of the API might suit his needs.

A long list of frequent changes means your API isn’t yet stable enough. On the other hand, no changes at all may mean your API might be out of support.

Preliminary requirements and agreements

Your product may require initial Agreements between parties or specific Technical prerequisites to be satisfied.

Under agreements, it may be:

• Sign papers and contractual obligations
• Communication via some channel
• Exchange certificates and additional pre-generated data (for example, this is a way to connect parties using SAML)

Under Technical prerequisites, it may be:

• Establishing a secure connection by creating client/server instances, IP whitelisting, VPN, etc.
• Generating clients
• Setting up test data to be used for certification/testing period

This part should also describe a high-level workflow that outlines everything that needs to be done before you and your party can move on to the next phase.

In other words, this part explains where to start: whether the development team going to initialize this integration, or should it be initialized by middle or upper management?

Technical workflow

Diagrams. Steps details. Code examples. Everything matters. Do not stop on diagrams only or code examples only.

One confirms another, so by looking into code example, as an API consumer, I should look at the diagram to figure out “where am I in the general process?”.

By looking into the diagram, I should read what validation rules to apply for a specific method call.

If you use some industry standards, then refer to the URLs with descriptions.

Validation rules and limits

Data formats and validation rules are the most frequently forgotten part of the documentation, but it’s one of the most important. It eats a lot of time to communicate and figure out what might be wrong when my request fails.

Validation schema in any format would save a lot of effort.

The same applies to the limits of usage. If you have any limits to the number of requests, the number of users, amounts of data transferred, don’t forget to mention this.

Test data provided

The best case for an integration developer is to write a simple curl command to check that connection is working.

Honestly, I never seen this provided by default. But as a fan of the unit and integration testing approach, I always ask for it, so it can be used in CI/CD pipeline to ensure stability.

Terminology index

It’s okay to use terminology that is specific to the knowledge area or the field. But it’s not unusual for an unprofessional user to read this document.

Reduce ambiguity and let people learn more about the field through reading your documentation. Sometimes, good examples of documentation become an anthology of the area.

Last but not least

Always request and appreciate the feedback. It’s a good idea to ask for some metrics like:

• How clear was our documentation to you?
• How much did it take for an initial review?
• How fast did you identify your questions to clarify?
• How many questions did you have after the initial assessment?
• Etc.

It’s better to make a little quiz like this and aggregate this information before your customer finished the integration and forgot about it.

Thanks

Feel free to add more suggestions and your point of view in the comments. I will summarize it at the bottom of the article.