Guidance

Describing RESTful APIs with OpenAPI 3

Updated 28 September 2023

© Crown copyright 2023

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.

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.

The government chooses standards using the open standards approval process. Read more about the process for the OpenAPI 3 specification.

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

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.

5. Specification review date

The Open Standards board will review this specification in June 2020.

Back to top