Three Elements of a Good API README
Sometimes, offering an API README is enough. What are the elements that make it good?
I understand you don't have the time or the resources to offer good API documentation. Well, at least try to put together a single-page README that consumers can understand. It's what I feel is the bare minimum. Even more so if you're sharing your machine-readable API definition via GitHub. From a consumer perspective, finding a good API README is a sign there's someone taking good care of the API. What are the things that a good API README should have, then? Let's explore.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
There's a clear difference between a README and a full API documentation. More than one, actually. First, while the goal of a README is to focus on brevity, a full API documentation has the goal of providing comprehensive information. Then, the location of a README is usually a code repository. On the other hand, you can find the documentation for an API on its own Web site. A README acts as the front door to an API, offering consumers brief and sufficient information to get started. A full documentation is a place where consumers go to when they need to find information about any detail of the API. Having one doesn't mean you shouldn't have the other. But, having a README is, in my opinion, the very minimum you can do if you're serious about your API. And, at the very minimum, there are three elements I'd consider.
The first thing to think about when preparing a README is sharing an overview of the API. This is where you get to explain what your API does and what consumers can get from it. You include the problems your API solves, its most important features, and who your API's preferred audience is. The goal is to capture potential consumers' attention so they can quickly understand if this is the right API for them. A simple formula I use is splitting the writing into a first paragraph summarizing everything, followed by two more paragraphs. The second paragraph details the benefits of using the API, and the third and final paragraph shares the most important features. If someone reads nothing else but the overview, they get enough information to understand what your API is and what they can get from it.
After reading the overview, some people will want to use the API. The second section of your README is called "Getting Started" and is for those people. Its goal is to provide enough information to show anyone how to start using your API immediately. The two critical steps you need to address in this section are the API authentication and how to make a first request to an operation. These two steps are essential to go from not knowing how to use your API to being able to make requests. The complexity of the documentation depends on the authentication scheme you're using. So, if you're using something simple as an API key, you can write a basic explanation. If, on the other hand, you're using OAuth 2.0 or something more sophisticated, you might need a better explanation. Possibly, you'll even need to provide authentication examples in different programming languages. Consumers should be able to follow your guidance and successfully authenticate themselves to use the API. To help consumers test their authentication, you provide an example request to a meaningful read-only operation. After this point, consumers are able to make authenticated requests to any of your API operations. Now they want to know what other features you're offering.
The third important element of your API README shares practical information about the most important operations. Your goal is not to list all operations and effectively replace your API reference. Having a full reference generated from a machine-readable definition is much better. Instead, what you want to achieve here is to provide just enough information so consumers can choose which operations they're interested in and, if they want to, consult the full reference. A tactic to get quickly to the point is to describe what each operation does and follow immediately with an example of how to use it. Then, provide a couple of alternate usage examples and a link to its full reference where consumers can understand all the parameters, response payload, and other details. If you're a consumer, you want to quickly make requests to operations you're interested in. It's only after succeeding in making a request that you'll want to fully understand what you can do with the operation.
If you offer an API README with the elements I just shared, you'll be able to offer consumers help when they need it the most. You'll also be able to attract those who are evaluating your API and unsure if it's the one they should be using. In summary, consumers who can quickly understand what your API does and immediately make a successful first request to an interesting operation are the ones who will stay with you for the long term.