Documenting APIs
Structuring, designing and publishing your API documentation
API documentation helps developers and technical architects:
- discover your API
- know if they can use your API
- understand what your API is for
- integrate with your API
To help your users use and understand your API, it’s important that your API documentation is more than just an API reference page or an auto-generated API specification.
This guidance helps you write clear, well-structured API documentation for developers and technical architects.
The Central Digital and Data Office (CDDO) technical writing team provides training on structuring and writing API documentation. Email technical-writers@digital.cabinet-office.gov.uk if you’re interested.
Understand the needs of your users
Start with user research and defining user needs.
User research helps you structure and write your documentation based on what your developer and technical architect users need, instead of how your team thinks about your API.
User research also helps you understand your users’ technical ability, understanding of related topics, and familiarity with terms or acronyms your team uses. This helps you write documentation that’s clear to your users.
You can learn more about user needs and content in the Government Digital Service (GDS) Introduction to Content Design course on FutureLearn.
Structure your documentation
You should structure your API documentation to:
- tell users what your API does
- give a conceptual overview of how your API works, if your API is complicated
- get your users started by taking them through a simple request and response
- give task-based guidance that takes a user through using the API to complete common tasks, and integrate and test the API
- include an API reference that lists every detail of your API
- support your users with information on versioning, API status and getting support
Do not structure your documentation by user type or experience level. Research shows users find it hard to know which user category they belong to, which makes it more difficult for them to find the content they need.
You can look at API documentation for similar APIs to yours, or look at documentation from other products such as GOV.UK Frontend, Stripe or MailChimp.
If you provide client libraries to interface with your API, you may need to produce separate documentation for each client library. For example, GOV.UK Notify has separate documentation for each of its client libraries.
Introduce your API
Start your documentation with a short overview of:
- what your API does and does not do
- whether your API is in the alpha, beta or live phase
- the benefits of using the API, so users can compare it to other APIs
- whether it’s free to use
- whether your users need to build or buy anything before they use it (technical prerequisites)
- who can use your API, and any restrictions on using it or its data
Avoid trying to sell your API. Describe features as benefits for your users instead.
Keep your introduction short, so your users can read and understand it easily. For example see the GOV.UK Platform as a Service (PaaS) introduction page.
Give a conceptual overview of how your API works
Include a section about how your API works conceptually, if your API is complicated and users must:
- understand and use a sequence of API requests and responses
- understand how different backend systems interact
Only include this section if you’ve discovered a need for it in your research and tested it thoroughly. This is because conceptual information can:
- get in the way of developers finding the task-based guidance they’re looking for
- be ignored or only partially read by developers
You should write this section as an explanation of flow or a sequence of steps, using numbered steps if possible. For example, see How the Document Checking Service works or How GOV.UK Pay works.
Get your users started
Provide a ‘Get started’ section to take your users through the quickest and easiest way of getting an example response from your API.
You can use a short, numbered list about making a test request and response with sample code. If your API uses authentication and authorisation, include a step on getting a test API key.
Do not include every possible request variable or response parameter, or multiple examples. Link to more detailed explanations elsewhere in your documentation if you need to.
At the top of your ‘Get started’ section, you should include:
- the URL of the API, for example
https://catfinder.api.gov.uk/ - any HTTP headers your user must include in each request
- the format of requests and responses, for example JSON
- how to apply authentication and authorisation if your API uses them
Do not explain the basics of how APIs work, or how authentication and authorisation work. You can link to external explanations by following the GOV.UK external linking policy.
Link to your browser-based API ‘sandbox’ if you have one, so your users can try out requests and responses.
Write task-based guidance
Task-based guidance helps users complete the most common integration tasks, based on the user needs from your research. Most of your documentation should be in this format.
Good examples include:
- Refund a payment - using a REST API
- Deploying apps - using a native API
Your team’s developer, user researcher and technical writer should work together to identify the most common tasks your developer users need to complete.
Each task-based guidance section should:
- help users complete one task
- have a front-loaded title that starts with a verb
- include example code for a request and response
- include descriptions for the request parameters and response fields that relate specifically to the task
- avoid duplicating basic information about the API - link to your ‘Get started’ section instead
- link to any tasks that users need to complete afterwards
Task-based guidance should be more detailed than just a description of an endpoint and method. You should guide users through the task by:
- talking directly to your user - use ‘you’ and active verbs
- using the active voice and plain language
- describing the task not the technology - tell your users what they need to do, instead of describing how the system works
- using numbered steps wherever you can
Keep task-based guidance concise. Do not include every possible request or list complete API responses. You can link to your API reference for users who need more detail.
For each task, you should tell users what to do if they have a particular need - for example a common alternate request, they get an error, or something goes wrong in the API flow. Add a front-loaded heading and section for each need. Include these on a page with the task - do not create ‘troubleshooting’ or ‘FAQ’ pages.
Write about testing the API
One of your sections of task-based guidance should help your users successfully test your API, especially if they want to use your API in a production environment with real data.
Explain how a user can test whether their interactions with your API are working properly, including how to run the tests in a test environment.
If you have a sandbox environment where developers can experiment with your API, you should clearly explain the limitations of your sandbox environment compared to your production environment.
For example, if your sandbox environment only allows stateless testing, your users should know it is not as representative as stateful testing in production.
Include an API reference
Use an API reference page to list your API endpoints, methods, requests, responses and errors. You should auto-generate your API reference rather than writing it by hand, so it’s easier to keep your API reference in sync with your API code.
Follow the guidance on writing API reference documentation.
Support your users
You should include sections that help your users with general rules about using your API, and what to do if there’s a problem.
Rate limits and timeouts
If your API uses rate or record limiting, explain how many requests users can make within a set period.
Even if it’s unlikely a user will meet the maximum number of requests, you must still explain:
- what happens if users exceed the limit, including the type of error message they can expect
- how to correct the error
- how long they need to wait before they can make requests again
For example, the GOV.UK Pay API documentation explains that the user will see a particular error code, but they will be able to make another request after 1 second has passed.
Versioning
Tell users:
- how versioning works for your API
- how to keep up to date
- where you’ll publish information about what’s changed when you release a new version
You can also version your documentation, so users can switch between documentation for different versions.
Support
Your support section should help users to:
- contact the API development team
- tell you about issues or gaps in your documentation
- contribute to development, if appropriate
- find any supporting information or guidance, for example product blog posts
You should explain how users can report any vulnerabilities or security concerns and how you respond to these reports. You can also ask users not to publicly disclose any issue until it has been addressed by your development team.
For example see the support section of the Document Checking Service documentation.
Status
Include or link to a status section that tells users whether your API is available, and provides them with regular updates when there’s an issue or incident.
Write your documentation
Technical documentation should be written in the same style as other GOV.UK content. This means you should write in short sentences using plain language, and follow:
- GOV.UK style
- guidance on writing for GOV.UK
- guidance on making your content accessible
Only use technical terms without explanation if you have evidence showing your users are familiar with them.
Format code snippets
Code snippets are small blocks of reusable code.
You must make it easy to tell the difference between code snippets and non-code text, for example by rendering snippets in a fixed-width font. You might also find it helpful to provide a light background colour to make it stand apart from standard text.
For example, the Technical Documentation Template uses a light grey background for inline code and code blocks.
Make sure that code snippets:
- work if users copy and paste them - minimise placeholder variables or make them obvious
- only contain code - do not include line numbers or a Terminal prompt, to make copying and pasting easier
Writing about third-party products
Avoid writing your own version of third-party documentation. You should link to the third-party’s own documentation instead, so you do not need to update your own version every time their version changes.
Help users navigate your documentation
API documentation can become long and complicated. Consider how to help your users find the part of your API documentation they need with a navigation. For example, the Technical Documentation Template uses fixed navigation so a user can move to different sections, and can render content as either single or multiple pages. This is a common documentation navigation design used by organisations including Stripe and Dropbox.
Research shows that developers use Ctrl+F frequently to search documentation. But if you have a lot of documentation, you should add search functionality. The Technical Documentation Template has an inbuilt search function.
Add metadata to help your users find your documentation. Consider including the name of the API, whether it’s stable or in alpha, the base URL, version number, and availability information.
Publish your documentation
When your API reaches the alpha phase, host your documentation on a subdirectory of your .api.gov.uk domain.
You must not publish alpha, beta or live API documentation:
- on a service.gov.uk domain
- outside of .gov.uk - for example on a third-party service such as GitHub or GitHub Pages
Use the GOV.UK Design System to make sure your documentation’s design and functionality is consistent with GOV.UK and meets user needs.
The Technical Documentation Template allows you to publish documentation with a GOV.UK theme. It uses a static site generator called Middleman. The content can be written in HTML or Markdown and is stored as code, which allows it to be kept in version control systems such as Git. This industry approach in treating documentation as code is often referred to as ‘docs-as-code’.
Follow the API design guidance for more guidance on when and how to publish your documentation as your API develops.
Test your documentation
Test your documentation regularly to make sure the content continues to meet user needs.
Publish your documentation as early as possible to get feedback from users. You should regularly test active API documentation, especially if you introduce any changes that affect how a user would consume the documentation or use your API.
For example, you can ask them to complete common scenarios with your API and see if the instructions you have provided in the documentation help them to complete a task. By observing your users following your documented instructions, you can see whether your documentation is incomplete, unclear, or helping users effectively.
You can also test your users’ understanding of the language you use in your documentation with comprehension testing. Common ways to test comprehension include asking users to highlight parts of your documentation that make it easier or harder to understand a concept or use your API.
You can also interview users to find out how comfortable they are with your API’s subject area and how your API works. You can even run A/B tests to test variations of content before publishing.
The HMRC API documentation team has also experimented with using pop-up surveys to get immediate feedback from developers using their documentation. The team then uses the responses to iterate the documentation.
Updates to this page
Last updated 17 January 2022 + show all updates
-
Updated to a new version of the guidance.
-
First published.