Writing better API documentation: a few lessons from enterprise integration

Over many years working on API integrations, I’ve seen a whole lot of ways that the experience could be less frustrating. This isn’t a definitive list but a personal collection of a few recurring problems with documentation I’ve seen in different REST APIs that could be avoided.

Explain what a field does

Consider API documentation like this:

String[] tags - “This field contains tags for the post.”

This is not helpful. The field name already told me that it contains tags, and tags generally are a collection of strings.

Now consider if the description said something like this:

Tags for posts appear in the web UI and can be used by users to search, discover and filter posts.

This not only tells the developer what the field does, it also helps them in working out if it is the right field for the task they’re trying to achieve.

Tell developers how a field or structure in an API behaves

Again consider:

String name - “The user’s name”

What sort of name? ‘Wallet’ name (i.e. the name one uses on a passport or payroll), a nickname, a username?

What does the name do? Is it publicly visible? Is it visible only when they interact with people? Is it unique? i.e. can two users have the same name? If so, what happens to previous references if the name changes? Do URLs break? Are there any rules about long names - would that break the UI?

You don’t have to answer all of those. But contrast it to something like this:

User’s name, displayed on their profile page and on any comments they post.

I now have some idea on the likely privacy or application-level significance of setting or changing the name.

If you’ve got something like a user resource, and you’ve got a web view showing the user, show or tell how the fields in the REST request/response map to the UI. If the developer can’t surmise from your API documentation “if I change field X, I’m reasonably confident this bit of the UI will change”, then the API documentation could be improved to ensure the developer understands.

Use the same names in your API as you use in your product (or at the very least, make the association clear)

Imagine you’ve got a developer-focussed name for a feature - something nice and boring like ‘Custom Enterprise Integration API’.

Marketing have decided that’s boring and not memorable or sellable and so have renamed it Sparklefluff.

In the API docs, explain that it is marketed under the name Sparklefluff, and link from the API docs to the page on your site that sells users on the wonders of Sparklefluff.

If the developer doing the integration is talking to internal users in the company they are working for, it is likely that non-developer users will use the product name that the marketing people have spent lots of time and resources coming up with, rather than the boring technical name that the developers used in the API. If you don’t make the link apparent, they risk talking past one another. You probably want your customer’s integration developers and the internal users they serve to understand each other better so they are more successful in integrating your product via the API. That’s made harder if you use different names for the API and the marketed product or don’t make that link clear.

Understand the constraints of developers building integrations

Developers doing integration may often not be a user of the tool in question. You’ve sold it to the company with shiny marketing and well-designed induction screens (and possibly some boozy, expensable lunches), but developers reading the docs may be learning what the product does and how it operates for the first time while reading it.

Developers reading API docs may have just an API key and no access to the web UI. Getting user access may be a tiresome, bureaucratic process or not possible for security/privacy/legal/some other reason. Don’t assume they know the product, explain how it works in the documentation.

Documentation isn’t the only way around this: improving the wider developer experience is. There’s a bunch of routes towards that such as:

• making it easier to get sandbox/test/dev accounts
• ensuring prototyping integrations doesn’t count towards per-seat costs or other limits
• making it reasonably easy to get answers from developers at the company
• having API explorers so developers can prototype queries in the browser

Conclusion

API documentation is the primary interface between your product and the developers tasked with integrating your product via APIs. If API integration is a thing that makes your product commercially valuable, ensure they have a good experience through detailed explanations of not just the mechanics of using the API, but how the API works with the product itself, which the developer doing the integration may not be very familiar with. They most likely won’t know much about your accounting software because they’re not an accountant, nor will they know much about your medical records software because they’re not a doctor—for a lot of developers, the developer documentation and other API tooling is not just their introduction to your API, but their introduction to your product.

Daniele Procida’s 2017 talk The four kinds of documentation is still worth watching to better understand the different types, purposes and goals of developer documentation, along with a lot of the resources on Write The Docs.