Writing REST and OpenAPI documentation for a broad audience

One author’s theory of how to write usable documentation without going crazy

The key to a useful API is documentation. You could have the most gloriously orthogonal REST API or a crummy half-baked SOAP service — the technology behind your API is less important than whether a developer can use it to get their job done, and documentation is what makes it possible.

So, for this article, let’s set aside all those arguments about API design, backend technologies, and the like. We will talk exclusively about documentation — how can we write docs that the broadest possible audience can find useful, regardless of what the API is or does?

Your API documentation should be written with a broad audience in mind (creative commons, rawpixel)

Understanding the types of people in your audience

One of the foundations of modern marketing theory is that you need to consider the personas of your customers. Different types of people will be expected to use your product in different ways. Our documentation should get them the same information but in a manner that’s useful to them.

I wrote in the past about my theory of developer personas. I perceive five primary types of developers, and our goal will be to help out as many of them as possible with the minimum amount of work. Here they are:

• Reference Ron — Wants to find the answer to their questions with no nonsense and no distractions. This is the sort of person who complains about a recipe website when it has ‘irrelevant’ personal interest stories at the top of every page.
• Ellie Example — Someone who wants to have a fully working program so they can tinker with it one change at a time. You can’t just give them a huge pile of LEGO blocks, they find it daunting to start from scratch.
• Tommy Tutorial — Prefers a story about why this program works and why it’s useful, not just how to write the code. Learns more from another developer’s perspective than if they just hacked together a solution.
• SDK Sally — Happy to write code themselves, but they really like to discover a toolkit in their favorite package manager. They expect a solution to provide autocomplete and hover-docs in their IDE.
• Conference Carl — Only wants to talk to a live person. Can only build trust by chatting with someone who knows what they are doing.

So the theme I get from thinking about these people is: I should create an ecosystem that includes an SDK and example code, and then I should write blogs about the work I did to create it. In theory, some of this work could even be the topic of a talk at a local event or webinar to appeal to Carl.

Read on for how I provide content to these five personas in a unified way.

Enforce reference documentation in code

A great debate I have with other API designers is: Should I write an API spec first, or should I have developers write the code first and then export its spec from the code?

I tend to come down on the side of “export the spec from the code”. Why?

• It is incredibly easy for the spec and the code to diverge. When you export the spec from the code, it forces you to notice when a developer has added something the designer didn’t foresee.
• You can write unit tests within your codebase to assert that every API and every data model has documentation. For example, I have unit tests to enforce swashbuckle documentation in my DotNet/C# API.
• If someone accidentally changes an API in a way they didn’t intend, the spec will change. You can diff this version’s spec against a previous one to see what changed.

My preferences mostly apply in the OpenAPI / Swagger ecosystem, but most other API toolkits also provide automated documentation generators nowadays. With a bit of work, you can create an automated test suite so that every pull request will enforce standards for your API documentation.

What is basic documentation, anyway?

At a minimum, an API endpoint is a method or a function your software provides as a service to developers who want to call it.

To work with external developers, you need :

• Name — A three or four word description of what the API is and does. Think verb / (optional adjective) / noun. This is what you call the API when you’re talking with a customer. It must be short and snappy so that you can be very clear with them via email or phone calls. Call it “Create Company” not “Add a new company to your workspace”.
• Summary — A single sentence describing what the API does. In good journalism, an article starts with the most important facts and then goes into more detail each following paragraph. The first sentence in your API description should explain the method in as few words as possible, and it should stand alone as the first paragraph. If you’re tempted to write a really long name, use that as a summary instead.
• Category — This is a portion of the description that gives the reader context into the wider picture about the API’s place in the ecosystem. If this API is a single Widget method within a dozen methods related to Widget handling: write a paragraph that explains widgets. Use this paragraph on every API endpoint about widgets.
• Special Cases — The final element is an explanation special cases. You know these ones. Maybe you found a bug where the user can’t delete a record within 100 milliseconds after creating it. Maybe webhooks are only fired 5 seconds after the data changes. Whatever your weird condition is, explain it at the bottom.

The end result might end up looking like this brief example from the ProjectManager.com REST API v4:

Docs for an API that checks the currently logged in user (ProjectManager developer site)

In this example, you see the API name, RetrieveMe. The first sentence of the description is a tiny executive summary. We don’t have category boilerplate since this is the only method in its category, but the remaining text explains the special use cases.

How should I structure my documentation?

It’s easy to get caught up in unimportant decisions like naming patterns (e.g. camelCase, PascalCase, or snake_case), pluralization (“Create Employee” vs “Create Employees”), and the like. Your API will be fine whatever you choose; just choose a style and be consistent.

Let’s instead talk about something I am fully invested in:

Make sure each API method and each data model has its own page.

Do NOT use one of those documentation sites where your entire developer material is rendered in a ten mile high scrolling monstrosity.

Why?

• If I hit Ctrl+F to find text on the page, I want to find text on the page I’m viewing, not text five miles up in some other method.
• If I nudge the scroll wheel a tiny bit, I don’t want the page to jump a thousand lines down.
• If I share an API URL with someone else, I want them to see it quickly and not wait while their web browser renders a massive epic novella.

That said, there are people other than me who have equally strong opinions in the other direction. If you must use one of those sites, just know what you’re doing.

Repetition is necessary

One of the foundational lessons of software engineering is don’t-repeat-yourself. But at the same time, repetition is necessary to write good documentation. I’ve already talked about how a good category description can be reused on every API endpoint within the category.

Why is this?

Repetition is necessary because developers using your API documentation are in a rush. They are hurrying to get something done. They don’t want to spend hours reading a complete essay, they just want to find an answer.

If you make sure that each piece of content exists in your documentation only once, a developer can easily miss it. The person might do a search, find one page, see that it doesn’t answer their question, and then link to the next one. This can happen a dozen times before they find what they want.

When you have a really useful piece of documentation, it’s worth repeating it a few times. Remember that all of our different developer personas will come to the page with their own agenda and their own assumptions.

I don’t know in advance why a reader might skip one page and read another one. But they do it anyway, and that leads me to copy some text.

Writing SDKs and example programs

One of the original theories of REST was that the concept made API calls so easy “no example code was necessary.”

This is no longer true. Why?

• Modern APIs have lots of optional features that can distinguish a hacky implementation from a good one. Think SSL connection pooling, compression using GZIP or Brotli or something else, reliable detection of timeouts, automated retries, or something else. If you just tell all your developers to write their own code from scratch, they will make the same mistakes over and over.
• Modern development environments like Visual Studio Code provide so much utility with autocomplete and hover-docs. If you demand that your customers write their own code, they will miss out on all these usability and productivity features.

The good news is that it’s possible to auto-generate an SDK using a toolkit like Microsoft Kiota or my own SdkGenerator. I routinely experiment with new SDK generators, but I find that I tend to customize my SDK heavily and so I tend to gravitate towards code I have written myself. Your experience may vary.

That said, once I’ve published an SDK, I like to set up GitHub actions to build/test/publish new versions of the API. I can submit a pull request with auto-generated patch notes for each new edition of the API, and it automatically includes all my reference material directly in an IDE.

The end result is an SDK that is:

• Discoverable — A developer can easily find a new method by using autocomplete within OpenAPI categories and methods.
• Self-upgrading — If a developer uses an obsolete API, when they upgrade to the next version of the SDK, they can see your advice on how to replace the old method with a new one.
• Optimized — All your own tips and tricks to increae API performance or utility can be baked into your own SDK.

Write your own examples, tutorials, and presentations

The final step in this process is to use your own SDK and write small programs using it. Each program you write should become a blog post as well as example code published using the MIT license, as well as potentially a presentation you can give at a webinar.

This part is, unfortunately, the most time consuming. The goal here is not to write a million programs; it’s to write a small number of them and leverage the result as many times as possible. Repeating yourself is okay! You won’t reach the same people each time.

If I do my job successfully, I can spend a four hour period writing a small program, and then spent another day repurposing this content into other forms. It makes each program take a little bit longer, but the end result is that my documentation is useful for different personas.

Is documentation really the only thing that matters?

Once you have documentation that is good enough, the next battleground is your API’s quality. If developers can figure out how to use your API, they will start finding all sorts of bugs and issues and nuisances in it.

You need to have a strategy for gradually deprecating old or less useful APIs and replacing them with ones that better match your customers’ expectations. Don’t be afraid to deprecate parameters and replace them! If you’ve done a good job shipping an SDK for your developer audience, they will automatically notice the changes every time the API updates.

If you’ve taken care up front, your API will stand the test of time. There are real advantages to modern orthogonal REST APIs using the CRUD+Query pattern. Your API must allow users to create, retrieve, update, and delete records. You must offer a flexible query language for fetching multiple records like GraphQL, OData, or Searchlight.

So I encourage you to write good documentation, but I also want to emphasize that winning in the marketplace requires lots of different qualities. Good documentation is just one element of a winning strategy — but it’s often overlooked. I hope you’ll emphasize the value of good documentation to your team.

Ted Spence heads engineering at ProjectManager.com and teaches at Bellevue College. If you’re interested in software engineering and business analysis, I’d love to hear from you on Mastodon or LinkedIn.