Lorna Jane Mitchell - Beyond the API Reference: Developer Experience for APIs

The highest level obstacle to consuming APIs is the lack of documentation [*].

Respondents with 6+ years of API development experience were more likely to mention lack of documentation than those with 0–5 years of experience.

If your API doesn’t have a really good documentation, it’s not an API. If no one can use it, don’t publish it in the first place.

API Experience menu

• Getting Started Docs
• Authentication Overview
• Common Tasks
• SDKs and Libraries
• Request/Response Example
• Human Contact
• Tools Platter
• Troubleshooting Guide
• Extras like video content, code snippets, and demo apps

In general, people don’t order the whole menu at once, they discover the selection in a series of different visits. They choose enough to satisfy their needs. What you have to do is to direct the resources you have to make the best impact you can.

Getting Started Content

• Overview content that introduces developers to the landscape: architectural style, authentication method, response format, etc.
• Include working examples that developers can copy-paste and try out.
• Add links to any resources and dependencies that developers need to know and have to start using your API.

Every API is someone’s first API. So don’t be afraid to over-explain things.

Include example responses in the API reference

Utilize the capabilities of the OpenAPI specification format, give as much context, and as many details as you can.

Examples of requests and responses can fill a gap for all sorts of use-cases.

Code Samples

Use copy-and-paste examples to get developers to start using your product quickly. The more examples you have the better.

HowTo Guides

How to [...] X with Y, where X is a common task or goal, like sending an SMS, or taking a photo; and Y is a tech stack that you can use to solve that task or reach the goal. These guides can be individual sections, articles, blog posts even.

Troubleshooting Guide

aka FAQ, or sometimes Tips & Tricks

• A dedicated place for common solutions to common problems: ask support people or check developer forums
• Don’t have to be finished immediately - it’s a living document

Recommended Related Tools

If there are tools that work well with your products, like for local development, for API calls, for mock API servers, etc., share them!

Demo Apps

Use working but minimal versions of likely applications:

• Plausible but not super-complex
• Pick your favourite use-cases
• Take inspiration from your Sales’ “verticals”
• Mix up technologies to appeal to different communities

SDKs

Only ship what you can support! Don’t be afraid to do a quite limited installable package. And just like with your APIs, documentation is key.

Be Real, Be Visible

• Don’t hide behind your company, or a brand, or a team: you don’t have to be available all the time
• Use your name
• Direct people where they can find you: be part of the conversation

[*] based on the article called 2020 State of the API report published by Postman.