What Sections Should be Included in an Effective API Document?

I worked heavily on API products, searched for answers to many questions, benchmarked many API docs, and revised our document accordingly. I've understood that an API doc must be comprehensive and transparent enough for developers to connect with minimum questions and user-friendly enough that even business-operation-oriented teams can understand your features and flows. The sections below can help you achieve these goals and make your audience comfortable, whether you have a small or big API.

Introduction and Overview

In this section, I like to write a couple of sentences that describe the primary purpose and mention its target customers. In the beginning, we should detail the user types, such as standard and enterprise, and API types, such as REST and XML. Following that, we must have a quick guide on how to start using the API, including prerequisites like authentication, versioning, or using different environments.

Authentication

In this section, we must detail the supported authentication methods (e.g., OAuth 2.0, Basic, Bearer, JWT, etc.), including how to obtain the credentials and how to use them in our calls. If our API has different access roles, we should note the differences in access levels under this section.

Endpoints and Requests

In this section, we must provide the base URL, including sandbox and production environments, if available, and other common patterns that endpoints follow. We can also mention how we organized our API doc. For example, in Logiwa, we organized our API doc by resources (feature groups). Examining the structure allows users to understand the overall intent. If we don't have a dedicated section for the limits, we must detail the API call limits, how often requests can be made, and how to handle throttling.

Request limits

This section requires us to provide the number of requests allowed per minute and the time gap required between sequenced calls. If we have multiple API user types, we must mention them separately.

Additionally, in this section, we must explain what users will face when they exceed the limits. What error code and description will they receive in the response? How much time will they need to wait for the next call? How will they be notified if they exceed the limits?

Moreover, if we have some batch endpoints, like an endpoint that allows 100 order creation in a single call, we should detail the collection size limits for each bulk endpoint. We should also mention what the users will face if they send 105 orders, which is greater than 100. Will 100 of them be created, or will none of them be completed? Which error code and description will the users receive in the response? How should the user handle the scenario if 100 are produced but 5 of them are not created?

Lastly, we should have a sub-section that details how to create rate-limiting strategies. For example, you may offer throttle requests, back off, and entry techniques, or if your API supports webhooks or graphQL, you can advise these.

Key features

This section is optional to me, but it's great if we have many features on our API. Under this section, we can highlight 5 to 10 key features, ensuring our users can easily understand the main functions and reach their content.

Popular Use-Cases

When working with APIs, there are always flows. For example, if a user needs to update her bookings, she first needs to retrieve them to see which details need to be updated. This was simple, of course; API docs often offer more complicated flows. It's a good idea to list these use cases in the early parts of documentation using hyperlinks, which is an excellent way to navigate users to the details.

In a flow detail section, we must mention which endpoints must be used in which order and in which way to achieve the goals. Make sure that the data flow and the business flow are clearly defined, including the field mapping between endpoints. It would be great if we could provide a flow chart drawing, making it easier for our users to imagine the flow.

Search and Filtering

Whether users create, update, or delete, they often first need to retrieve the data before taking action. Therefore, in this section, we should help your users understand your API's search patterns, streamlining their data retrieval process. We must detail the search parameter types our API is supporting, like query, path, headers, and application/JSON.?We must also mention how to use the pagination parameters and how the endpoints react. What will the system's reaction be if the pagination parameters are not used? In other saying, what is the default?

Status and error codes

Under this section, we must explain the HTTP status codes our API is using and their explanations. If our API does not align with standard REST API HTTP codes, we must define the error and success response schemes.

Additionally, we should list all the error codes, their explanations, and solutions, if available, as a table. Lastly, it would help if we detailed under which conditions or for which error codes the users should create a case.

Date Format

In this section, we must provide a specific format and the time zone for the date values our API expected.

Unavailable Operations

If our API is extensive and consists of many endpoints, it would be helpful to mention the unsupported features and flows because, most likely, our users need clarification with our features since there are many methods and flows to explore.

Resource Pages

Let's think that our open API is built for a Warehouse Management System. In this case, we would have different resources like products, locations, shipment orders, purchase orders, etc. In this case, we must group the endpoints according to their functionality as resources. Under each resource, we must clearly define the objective of the resource and the CRUD flow. If a resource is part of some critical flow, you can mention how the resource is used during the flow and backlink the flow's content.

Endpoint Pages

Under each endpoint section, we must clearly define the objective of the endpoint. We must provide the data or object type, explanations and constraints of request parameters, and response elements. We must also offer copiable versions of requests and responses, if possible, for all status codes. If there are confusing parts in some request or response elements, we must clearly define solutions to confusion. If the endpoint is part of a flow, it would be better to hyperlink that flow. Similarly, if an API needs data collection from other endpoints as a precondition, we should hyperlink those dependent endpoints, mentioning that the required data can be collected from there.

Webhooks

Webhooks are crucial for facilitating real-time updates without the need for constant polling and often increase the scalability. In this section, we must clearly explain how our API can notify users about events as they happen.

Webhook Setup: We should start by explaining how users can subscribe to webhook events. We must detail the required steps, such as providing a call-back URL endpoint that will receive the webhook data and registering it with our API. Additionally, if authentication is required during registration (e.g., via API keys or tokens), we should note it here.

Event Types: We need to define the events that trigger a webhook. For example, in a warehouse management system, events like "shipment created" or "order updated" would be common triggers. A complete list of event types and a brief description of each will help users understand when their webhook will fire.

Webhook Management: We need to cover how users can manage their webhook subscriptions, including how they can view existing subscriptions, edit them, and remove them. If we offer any UI or API endpoints to handle webhook configurations, we should mention it here.

Webhook Payloads: Here, we must provide the structure and format of the data that our webhook sends. Clearly detail the JSON object, fields, and their data types. If an event returns multiple types of response schemes, providing an example payload for each scenario helps users prepare their systems accordingly. For complex responses, we should include different examples to account for variations.

Limitations: There are always some limitations and their solutions or workarounds. Suppose webhook delivery isn't always guaranteed in our API. In that case, we should offer developers the option of implementing reconciliation jobs to fetch data from related endpoints periodically and take action for the missing events.

Postman Collection

If we are not using tools like Swagger and users are not able to execute examples on your API doc instantly, it would be great to provide pre-prepared Postman Collections to reduce the time developers need to invest in connecting your API. If we have a huge API and release new features very frequently, it may be hard to provide everything in Postman, but at least we can provide some for the most used flows.

FAQ and Troubleshooting

In this section, we aim to address some common questions and issues users may encounter when working with our API. By answering these proactively, we can help our users solve problems quickly without needing to reach out for support. For example, why am I getting a 401 Unauthorized error? How do I handle rate limits? What should I do if I receive a 500 Internal Server Error?

News

Under a news section, we should provide the upcoming development, depreciation, or retirement news.