We use some essential cookies to make this website work.
We’d like to set additional cookies to understand how you use GOV.UK, remember your settings and improve government services.
We also use cookies set by other sites to help us deliver content from their services.
You have accepted additional cookies.
You have rejected additional cookies.
Departments, agencies and public bodies
News stories, speeches, letters and notices
Detailed guidance, regulations and rules
Reports, analysis and official statistics
Consultations and strategy
Data, Freedom of Information releases and corporate reports
Updated 7 August 2020
© Crown copyright 2020
This publication is licensed under the terms of the Open Government Licence v3.0 except where otherwise stated. To view this licence, visit nationalarchives.gov.uk/doc/open-government-licence/version/3 or write to the Information Policy Team, The National Archives, Kew, London TW9 4DU, or email: psi@nationalarchives.gov.uk.
Where we have identified any third party copyright information you will need to obtain permission from the copyright holders concerned.
This publication is available at https://www.gov.uk/government/publications/recommended-open-standards-for-government/describing-restful-apis-with-openapi-3
OpenAPI is an API description format for RESTful APIs. The Open Standards board recommends that government organisations use OpenAPI version 3 to describe RESTful APIs.
You should consider using OpenAPI version 3 to describe any RESTful APIs you build. OpenAPI can describe an entire API, including but not limited to:
An OpenAPI description is not always sufficient to meet your users’ needs for API documentation. Complete API documentation includes other information such as quick start guides, how to get API keys, running a sample application, rate limits and many other subjects. You should refer to the guidance on documenting APIs and government API standards for more information.
The government chooses standards using the open standards approval process. Read more about the process for the OpenAPI 3 specification.
The challenge identifies the need to increase the consistency and accuracy of API reference documentation across government. Using the OpenAPI 3 specification should help to achieve this.
By using the OpenAPI 3 specification, you and other government organisations will be consistent in the way that you describe your RESTful APIs. You can use OpenAPI 3 to automatically generate accurate up to date API reference documentation, regardless of the programming language an API is written in. The specification can also help you to validate, version, maintain and update this generated documentation.
Using a consistent API description will help increase adoption of APIs across government by reducing time spent in understanding different APIs. You can benefit from the multiple OpenAPI tools available. For example, you can able to send test requests to your API endpoints using different methods in the interactive API explorer.
You can find the OpenAPI 3 specification at the OpenAPI GitHub repository. There are no software or hardware prerequisites to using OpenAPI 3. However, OpenAPI 3:
If you cannot use OpenAPI 3 to describe your API, you should assess whether another specification such as RAML and API Blueprint would be more appropriate.
The Open Standards board will review this specification in June 2020.
Don’t include personal or financial information like your National Insurance number or credit card details.
To help us improve GOV.UK, we’d like to know more about your visit today. We’ll send you a link to a feedback form. It will take only 2 minutes to fill in. Don’t worry we won’t send you spam or share your email address with anyone.
