Support
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.
Contact us
Your contact 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.