Writing API reference documentation – GOV.UK
The API reference is often the most important and used part of your API documentation. It is sometimes published on a separate page from the concept or start-up information. You must publish all the reference information together.
This guide assumes that you are following government API standards, creating APIs that are Restful, which use HTTP verb requests to manipulate data.
Generate API reference from code
You can write an API reference by hand or automatically generate a reference from comments in the API code itself.
There are many tools that allow you to automatically generate an HTML file from comments in developer code for display to your users. The advantage of this approach is that when developers update comments in their code, your documents will also be updated.
You will still need to tidy up the reference information once it has been generated and make sure it matches the instructions that come with it. Ideally, you will have a technical writer to help you do this.
You can use a number of criteria to choose between different automatic generation tools. In addition to standard considerations when choosing a new technology, you should also consider whether the tool:
- support the programming language you need
- output in an appropriate format, for example HTML
- supports any format options you might need e.g. code samples, tables, images
OpenAPI (formerly known as Swagger) is commonly used across government for RESTful API reference documentation. Alternative tools include:
- I / O Documents
- API plan
- JSON schema
What to include in an API reference
The API Reference describes everything the API does, including:
- endpoints and methods
- examples of requests and responses
- error codes
A resource is a piece of data or a collection of data provided by an API in response to a request, for example a row in a database. Provide a brief description of each of your API resources so that users are clear what they are used for and why they should call them. You can read more about the resources in Roy Fielding’s thesis.
Terms and methods
Under each resource description, list all endpoints related to that resource. Endpoints are the paths that a user will use (or call) to access or manipulate the resource. The API you are documenting is probably developed to accept standard methods in resource calls, for example GET, PUT, POST, or DELETE. Although these methods are standard, you should still list the methods applicable to the API you are documenting and describe their functionality.
Parameters and arguments
Parameters are optional filters that affect what the API will return. Next to the documented endpoints, you should list all the settings for that endpoint with a brief description. If you have different types of parameters, for example header and path parameters, it can be useful to group them by type.
Arguments are the specific input for a parameter. You may find it helpful to include them. For example, the GOV.UK Notify Python library documentation includes all possible arguments for each method.
Specify data types and constraints for parameters and arguments, and give relevant examples.
Examples of requests and responses
One of the most useful elements in an API reference is the sample code. For each endpoint, you must provide a sample request, with sample parameters (if they are available for that endpoint).
The request is typically posted as a code snippet using curl, but it can be helpful to view the request in different programming languages if available.
You must also publish a sample response as a code snippet, in the same programming language as the sample query. It should show the exact answer a user can expect from the sample query.
Be aware that your examples will not tell your user what the fields mean, such as whether the fields are optional or required, or if they have constraints. If this information is not clear in the example, consider including an explanation next to your example.
Error response codes
You must include specific error responses associated with an endpoint near the endpoint documentation or publish them together at the end of your API reference. Even if you only expect standard responses like 400 or 200, you need to interpret their specific meaning for your API.
For example, the GOV.UK Content API Documentation includes an array with the endpoint name, error code, what it means, and what caused it. This will help your users resolve any issues they might have with your API before contacting you for help.
Test your documentation
You should always preview changes to your documentation before you publish it. If you are documenting a RESTful API, you can test your sample requests and responses using curl or a tool such as Factor (free tool).
You may also find these guides helpful: