How to Write Good API Reference Guides

Technical documentation is a broad field with a lot of sub-disciplines. In previous articles published, we have covered steps on creating good tutorials and how-to guides. In this article, we want to talk about the most used guide by developers: API Reference Guides.

API Reference guides are barebone and straightforward. They provide developers with just what they want: the APIs or the software components.

You can think of API reference guides as trying to give a talk without beating around the bush, and just going straight to the point, delivering the talk, and saying nothing more.

It is for this reason, in fact, reference guides are most popular for API documentation.

They allow technical writers to easily curate a list of software components making up software machinery while helping developers (users of reference guides) have quick access to everything about software technology.

Good reference guides provide an easy way for developers to easily browse through a list of APIs, alongside short text descriptions to enable them to know the purpose of the APIs.

For instance, Stripe’s three-column one-page reference guide has now become an API reference guide standard used all over the world by various software companies.

It provides a simple interface, allowing developers to easily browse through a reference guide without having to open a new page; the three columns make it easy for developers to get all the information they need about an API, including the CRUD methods of the API and some code samples demonstrating the API.

What is a Reference guide?

Daniele Procida defines reference guides as technical descriptions of machinery and how to operate it. They are information-oriented in nature. This is in contrast to technical tutorials that are learning-oriented or how-to guides that are problem-oriented.

Creating technical tutorials and how-to guides is much more straightforward, easier to guess, and intuitive. We have all come across technical tutorials and how-to guides at several points in our lives even though not in the more standardized form as we have in technical writing.

Think of moments as a child when you were getting instructions from your parents on how to do a home chore, or a friend teaching you the newest game in town. These are forms of technical tutorials and how-to guides.

Reference guides, on the other hand, can be trickier to create. It would appear it is the only documentation content that sets apart technical software documentation from every other form/type of writing.

MUST READ: The Technical Writing Process: How to Produce steady high-quality content (2023)

Unlike technical tutorials and how-to guides, creating reference guides follows laid-out conventions and styles instituted in the software industry.

Due to this, the excellence of the technical writer in creating reference guides relies more on mastering these conventions than their writing prowess and creativity.

Moving on, we would look at the two main types of APIs reference guides used in documentation.

Types of APIs

There are two broad classifications of APIs:

Web APIs.
Native Library APIs.

Web APIs

When developers speak of API, web APIs are almost always the ones being referred to.

Web APIs, more fully known as web service APIs, are APIs that send and receive messages (payloads) using HTTP protocols to send requests(CRUD/HTTP methods) and receive responses. XML and JSON are the standard formats for sending and receiving messages via web APIs today.

Web APIs are language agnostic, meaning they are compatible with code implemented in various programming languages.

Web APIs have grown considerably over the years given their diverse utility to developers. Their growth in the digital space has reached a height where they have become stable enough for new business models to be engineered around them.

Web APIs have also evolved over the years. One of the earliest is the SOAP (Simple Object Access Protocol) APIs: web services that rely on a strict XML protocol to define the message exchange format for requests and responses.

This strict enforcement of the message format that characterizes SOAP APIs has coalesced in the development of the less strict but equally standardized paradigm for sending and receiving messages over the web: REST APIs.

Representational State Transfer (REST) APIs transfer messages using URLs, and endpoints serve as the means to access resources delivered in XML or JSON format. REST APIs have become the new standard for sending requests and receiving responses over the web.

Since the development of REST APIs, other web service APIs have been developed. These include GraphQL APIs developed by Facebook, RPC-based APIs, gRPC APIs, Voice assistant APIs, Internet of things APIs, and so on.

Native Library APIs

When developers use classes and functions from a programming language or framework, say React, they would usually just refer to them as classes or functions or methods, but the often unspoken way of referring to them is that they are also another form of API, better known as Native Library APIs.

Just like Web APIs, they provide developers with a simple interface (the classes and methods) that allows access to functionalities they do not know anything about how they are implemented.

MUST READ: How to Create A Good Documentation from Scratch

Unlike web APIs, however, they are implemented locally in a code project, where they are used to expand the operations that can be performed within the software project. Native library APIs do not need the web to be accessed and utilized.

Now, let’s talk about the five common sections involved in documenting APIs—web APIs specifically. Knowing these sections would be most useful in documenting any web API. We won’t be covering documentation for Native Library APIs in this article.

5 Common Sections in Documenting Web APIs

For illustrative purposes, we would be using sections from the Stripe API documentation in going through this section of the article. So let’s get started.

Resource description

A resource is an information returned by an API. Consequently, a resource description is a short text description that informs the developer of the information returned by an API. The information returned is called the response.

For instance, the Charge resource allows the developer to create, retrieve, refund, and retrieve all (as a list) Charge objects.

Following best practices, a good resource description should be between 1-3 sentences. Imperative sentences that start with a verb are best for writing resource descriptions.

Endpoints and Methods

REST APIs allow you to access resources using URLs. Endpoints represent the means through which you access a resource.

The URL to access a resource is usually made up of a base path and an endpoint. For instance, to create a charge (which creates a new Charge object), we would use this URL: https://api.stripe.com/v1/charges.

https://api.stripe.com is the base path; v1/charges is the endpoint that allows you access to create a new Charge object.

Methods, on the other hand, indicate the allowed interactions with a resource. Common methods include GET, POST, PUT, and DELETE. Basically, CRUD methods.

Following best practices, you must state a method and an endpoint together as in the image above, alongside a description of the endpoint informing the developer of the information the endpoint returns.

For better-organized API documentation, you can also go ahead and list the endpoints and methods associated with a resource as Stripe did here.

*All endpoints associated with Charge* (Source: Stripe)

Parameters

They are options you can pass to the endpoints to configure, constrain or influence the response you get for a request. Parameters are included in the request body.

There are several types of parameters: header parameters, path parameters, and query string parameters.

Header parameters are parameters included in the request header, which are usually related to authorization. Think passwords and API keys.

Stripe uses API keys for authorization/authentication. This is indicated by the -u prefix in the cURL code in the request example in the picture above.

MUST READ: How to Break Into Technical Writing (2023)

API keys are passed as header parameters in the request header.

Path parameters are part of the endpoints themselves. They are not optional. You can think of them as variables. For instance, in the “Retrieve a charge” endpoint, the id is passed as a path parameter to GET a charged object of that Id.

https://api.stripe.com/v1/charges/{id}/

where id = “ch_3LnhKa2eZvKYlo2C0AzA8CL9”

How to Write Good API Reference Guides: Path Paramenter — *Path parameter* (Source: Stripe)

https://api.stripe.com/v1/charges?amount=2000&currency=usd &source=tok_amex

Query string parameters are parameters that appear after the question mark (?) in the endpoint. The parameters and their values following the question mark are called the query string. It should be noted that the ordering of the parameters is insignificant.

Depending on the API endpoints, certain query string parameters might be required, and others optional as in the image from the Stripe documentation on creating a charge.

Request example

A request example is a sample request using an endpoint, showing some parameters configured.

Most API documentation always includes several request examples in different programming languages to make it easier for developers to implement the API in their code. This makes for a good user experience.

Response example and Schema

A response example is a response to a request example. The response example is not comprehensive of all parameter configurations or operations associated with an endpoint.

How to Write Good API Reference Guides: Response sample — *Response sample* (Source: Stripe)

The schema, on the other hand, is comprehensive of all parameter configurations or operations.

For good organization, the Stripe API documentation defined the schema alongside the Charge resource description at the start, while the response samples are provided for each endpoint associated with the Charge resource.

Summary

So that’s it for this article. This article is just a brush on the surface of creating API API reference guides or documentation. For a more in-depth understanding of documenting API endpoints, you can check the API documentation course by Tom Johnson.