© 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: firstname.lastname@example.org.
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
1. Summary of the specification’s use for government
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:
- available endpoints and operations on each endpoint
- operation parameters
- authentication methods
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.
2. How this specification meets user needs
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.
3. Benefits of using this specification
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.
4. How to use the specification
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:
- only applies to RESTful APIs
- covers the majority, but not all types of RESTful APIs
- cannot describe SOAP APIs or APIs that use GRPC or GraphQL
5. Specification review date
The Open Standards board will review this specification in June 2020.