Search results

API reference tutorial overview

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

I'm giving an API documentation workshop in San Francisco, California, on November 19, 2019. Check it out on EventBrite and register today to receive a $100 early bird discount.

In this API reference tutorial tutorial, we’ll work on creating five common sections in REST API reference documentation: resource description, endpoints and methods, parameters, request example, and response example and schema. To provide some context (and to continue with our sample documentation scenario), we’ll structure the information from the new endpoint to document into these five sections.

Five common sections in REST API docs

Almost all API reference topics include these five sections:

1. Resource description
“Resources” refers to the information returned by an API.
2. Endpoints and methods
The endpoints indicate how you access the resource, while the method indicates the allowed interactions (such as GET, POST, or DELETE) with the resource.
3. Parameters
Parameters are options you can pass with the endpoint (such as specifying the response format or the amount returned) to influence the response.
4. Request example
The request example includes a sample request using the endpoint, showing some parameters configured.
5. Response example and schema
The response example shows a sample response from the request example; the response schema defines all possible elements in the response.

Tutorial workflow map

The tutorial here includes a workflow map to help guide and orient you each step of the way.

After the tutorial

When we’re finished, the end result will look like a real API help topic (see the finished result in Putting it all together). In the associated activities, you’ll have an opportunity to edit or create an API reference topic with your own open-source API project.

Although there are automated ways to publish API docs, we’re focusing on content rather than tools in this section. In the next section, OpenAPI specification and Swagger, we’ll look at how to describe these same reference components using the OpenAPI specification. In the Publishing your API documentation section, we’ll look at ways to publish the information.

Next steps

Now that you have an idea of the tutorial, let’s get started with the first section: Step 1: Resource description.

50% Complete

50/146 pages complete. Only 96 more pages to go.


Want to buy me lunch? Click the Donate button below to donate any amount through Paypal.