Standout API documentation is no longer just a simple list of endpoints and fields. Excellent API references go beyond a list of ingredients. In our last article about API documentation, we discussed ways to improve the form factor of your docs and streamline your production process. But a smooth process and polished presentation aren’t much good without high-quality, usable content. In this article, we’ll cover the ingredients for great docs, so that you can be sure you are giving your users the recipe they need to succeed.
Basics are Essential, But Not Enough
When you look at the documentation for most APIs, you see content broken into at least two sections – Guides and References. A Reference section is like a list of ingredients. Without it, you don’t know what’s needed for a recipe. But alone, it’s not enough; you need to accompany your ingredients with instructions. Guides, use cases, tutorials, and other docs show context and help users turn those ingredients into a finished product.
Even _within_ your Reference section, there’s an opportunity to create a better developer experience. Potential users can reference your endpoint list and access them with a tool like Insomnia to explore your data. But if there is anything complex or innovative about your API that requires chaining actions, you’ll need to take a structured approach to organize your Reference section.
Without structure, users can be overwhelmed and bogged down searching for what they need.
A recipe for a complicated dish might include 40 ingredients, so a cookbook editor will divide them into shorter lists – for the marinade, for the active cooking stages, for the sauce, and so on, thereby making the recipe much easier to follow. You are the editor of your API Reference and can do the same, organizing by resource or by functionality.
Group by Resource to Focus on Data
Stripe’s API Reference is a good example of an API reference organized by resource. In object-oriented terms, a resource is like a model – it’s the ‘noun’ around which CRUD (create, read, update, delete) ‘verbs’ are grouped. For each resource, Stripe provides a clear, simple overview of allowed methods along with example usage and a brief explanation of the JSON object. Links to other articles anticipate other functionality that users might be interested in. The presentation is simple and focused. For an API with many different JSON objects, it’s an effective approach to put attention on one data object at a time.
List Your Endpoints in Digestible Sets
Twitter is a good example of an approach that’s more focused on how data will be used. The basic Twitter API (not including Ads) has only a couple of data objects, but a wide variety of ways that those objects can be related to each other. This section of their API Reference includes endpoints for two different data models – `users` and `tweets`. Instead of organizing each resource separately, Twitter has chosen to organize around what API users might want to accomplish with those resources. Clear headings, consistent format, and simple UI are evidence of how Twitter carefully planned the Reference.
API Reference sections need to be consistent and predictable. Users have expectations about what data they will find here, and once they are comfortable with your API, will want to be able to quickly scan and locate the details they need. Thoughtful planning pays off for this fundamental section of your documentation.
Guide Your API Consumers with Use Cases and Tutorials
Whether your users have extensive experience with your API or are coming to check out your documentation for the first time, you need to provide them with resources that show what’s possible.
A little cooking lesson illustrates why. Eggs, butter, flour, milk. With those four ingredients and nothing else, you could make hollandaise sauce, bechamel sauce, cream puff dough, popovers, crepes, spaetzle, and Dutch babies. Each of those recipes requires a different ratio of ingredients and different cooking methods, and each is appropriate for a different menu! If you only list ingredients, some cooks will improvise successfully, some will have scrambled eggs and a glass of milk, and some will just leave the kitchen altogether.
API documentation is similar to a cookbook. Your API enables a huge variety of applications which are like prepared dishes enabled by combinations of endpoint ingredients. An API consumer may have a very specific use case in mind when they come to you. You can shorten the on-ramp and help them get your API into their application faster by providing practical guides and simple examples. The sooner developers see success with your API, the more likely they are to continue working with it and recommend it to others.
HelloSign, an e-signature API company, makes a range of practical guides readily available to developers. They have code walkthroughs of common scenarios and detailed examples of specific use cases located in the same place as their basic API Reference, making it easy for developers to toggle back and forth between the ingredients and the steps of the recipe. Their technical blog offers even more ideas for using the API in real-world applications.
Publish Your API Recipe with Elements
Elements is Stoplight’s documentation tool for APIs based on OpenAPI. Linking your OpenAPI spec document to Elements gives you access to highly customizable, interactive API docs with embeddable web components. You’ll automatically get a high-quality API reference as well as intuitive tools to offer instructional recipes to your users.
Elements will provide your API users with a more practical, personalized experience. It allows much of the same functionality as desktop-based API tools like Postman but makes it available to developers right on your website. Customizing your implementation around the organizational ideas we discussed above will make it even more powerful, giving API users a hands-on way to see how methods and resources relate. Building Elements into your Guides can make for an exceptional developer experience, as users can experiment and test ideas as they are reading about them. Even the best cookbook doesn’t let you test and taste on the page!
Getting started with Elements is free! If you already have an OpenAPI Specification document, you can even test it out on our site by linking to your API.
