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 or write to the Information Policy Team, 皇冠体育app National Archives, Kew, London TW9 4DU, or email: [email protected].

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 /government/publications/recommended-open-standards-for-government/describing-restful-apis-with-openapi-3

is an API description format for RESTful APIs. 皇冠体育app Open Standards board recommends that government organisations use to describe RESTful APIs.

1. Summary of the specification鈥檚 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.

皇冠体育app government chooses standards using the open standards approval process. Read more about the specification.

2. How this specification meets user needs

皇冠体育app 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. 皇冠体育app 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 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 . 皇冠体育appre 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 and would be more appropriate.

5. Specification review date

皇冠体育app Open Standards board will review this specification in June 2020.

Back to top