Evaluate OpenAPI Specification as a common API description format

[benh-gds]

Evaluate OpenAPI as a standard for describing APIs

Can OpenAPI be the standard used to describe APIs?

Category

• [ ] Data
• [x] Document
• [ ] Technical
• [ ] Other Suggestions

Challenge Owner

I'm Ben Henley, a tech writer for GaaP

Short Description

OpenAPI/Swagger is a standard way to describe APIs. It provides a machine-readable description of an API which can be generated by the developers who work on the API. Swagger can be used to generate parts of the documentation, and to create tools like interactive API explorers. There are many tools available which understand Swagger. This makes it easier to maintain accurate documentation and update it quickly. At least two GDS projects already have Swagger descriptions of their APIs.

User Need

Developers who use government APIs need accurate documentation. If all projects that produce APIs were required to maintain a Swagger description, it would make it easier to introduce common documentation tools and make documentation more accurate.

Expected Benefits

Developers would benefit from more accurate API documentation and improved ways to learn about the APIs, like interactive tools. API documentation would be standardised and consistent between projects, reducing time spent for developers to find the information they need. This will increase trust in documentation and reduce time spent on support and increase the pace of integration. Tech writers will need to spend less time maintaining documentation. A Swagger description may also be required for other API-related tools, like monitoring services, management tools and API gateways.

Functional Needs

Teams must be able to produce and maintain Swagger descriptions of their APIs.

[paulhulme]

My view from Network Rail is that we have not used OpenAPI yet, but we have made use of swagger for internal APIs. I expect our future public APIs to continue in this direction, and using OpenAPI will be a good fit. Our current public APIs are mostly raw MQ, not REST. I think it would be good thing to back OpenAPI as an Open Standard for government.

[jonathanglassman]

All

I'm a technical writer within GDS, and am the new challenge owner.

Thank you for your feedback, both historical and recent, on this challenge. I have drafted a proposal to take to the Open Standards Board either in June or later in the year. This proposal is attached below.

Please be advised that this is a first draft, and I would like to invite any and all feedback on this content. This feedback can cover the overall approach, the subject matter covered, whether anything is missing, or anything else.

Please provide your comments by 8 May 2019. If you have any questions, please tag me in your comment and I'll respond to you directly.

Kind regards

Jon Glassman

[jonathanglassman]

Draft Proposal for feedback: Recommend OpenAPI3 to describe REST APIs

Introduction

This proposal is to recommend that government departments use the OpenAPI3 specification to describe their REST APIs.

Using OpenAPI3 for REST APIs means that departments would be consistent in the way they describe their APIs. It would make it easier when introducing common tools across government to read, display and update the API reference documentation.

The proposal is not a mandate as OpenAPI 3 may not be the most suitable API specification to use.

User need approach

The user need identified by this proposal is to maximise consistency in and accuracy of API reference documentation across government. Adopting the OpenAPI 3 specification should help to achieve this.

Users in the context of this proposal include government departments who create and maintain APIs, and need accurate API reference documentation. Individual users include but are not limited to developers, service managers, product owners and technical architects.

Achieving the expected benefits

If departments use the OpenAPI3 standard, they would be consistent in the way they describe their APIs. Departments would be able to use OpenAPI3 to auto-generate accurate and up to date API reference documentation irrespective of language. The specification will also enable departments to validate, version, maintain and update this generated documentation.

This could help increase adoption of these APIs across government by reducing time spent by departments gaining familiarity with different architectures. It would free up developer and non-technical resource as they would spend less time trying to understand the API. Departments will also benefit from being able to send test requests to their API endpoints using different methods in the interactive API explorer, as well as use other available tooling.

When OpenAPI 3 may not be suitable

The OpenAPI 3 framework is a powerful tool for working with and describing REST APIs. However, departments must assess if OpenAPI3 is the correct framework to document their APIs.

Firstly, OpenAPI 3 is for REST APIs only, and cannot describe SOAP APIs or APIs that use GRPC or GraphQL. Additionally, OpenAPI 3 covers the majority but not all possible styles of REST APIs.

Currently, OpenAPI 3 has a description of itself located at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema. The OpenAPI 3 machine-readable and verifiable JSON schema is still being finalised. This makes it more difficult to assess and verify if an API complies with the OpenAPI 3 specification. This could potentially lengthen the development time of an API written in OpenAPI 3 as it would be harder to spot and fix bugs and issues during development.

However, other validation tools exist. These assess APIs on non-schema criteria such as the API data and references. Some of these tools are located at https://openapi.tools/. Additionally, it must be noted that a JSON Schema validation does not guarantee compliance, because a JSON schema does not allow for validation of all use cases in the specification.

Departments should also assess what tooling is available for their chosen API specification. There are currently multiple OpenAPI 3 tools that enable users to, for example, validate their API (as mentioned above), integrate their API into web pages, or translate an OpenAPI 3 specification into another specification such as RAML. This tooling is regularly expanding, but is not fully comprehensive yet. Other API specifications also have tooling, for example RAML has multiple testing tools located at https://raml.org/developers/test-your-api. Departments should assess what tooling is most appropriate for their use case.

Other steps to achieving interoperability

This proposal is only concerned with promoting consistent and accurate API reference information across government. This is because the OpenAPI specification only covers reference information such as the API’s endpoints. Fully developed API documentation includes other information such as quick start guides, API keys, running a sample application, rate limits and many other subjects. Government departments should still write the non-reference parts of API documentation. This challenge does not include how government departments write their APIs (for example syntax, response format) or where those APIs live.

[chris-little]

@jonathanglassman I welcome this proposal, because the international meteorological community has started to move in this direction with its Weather on the Web API, building on the work for geospatial APIs in OGC and W3C with past and forthcoming hackathons.

I am a little concerned about the use of the term 'REST'. Apart from igniting theological architecture flame wars, we find that the key issue is the 'search pattern' as perceived by the end user rather than whether the API is truly RESTful or not.

[jonathanglassman]

Proposal for submission to the Open Standards Board: Recommend OpenAPI3 to describe RESTful APIs

Introduction

This proposal is to recommend that government departments use the OpenAPI 3 specification to describe their RESTful APIs.

Using OpenAPI 3 for RESTful APIs means that departments would be consistent in the way they describe their APIs. It would make it easier when introducing common tools across government to read, display and update the API reference documentation.

The proposal is not a mandate as OpenAPI 3 may not be the most suitable API specification for all use cases.

User need approach

The user need identified by this proposal is to maximise consistency in and accuracy of API reference documentation across government. Adopting the OpenAPI 3 specification should help to achieve this.

Users in the context of this proposal are government departments who create and maintain APIs, and need accurate API reference documentation. Individual users include but are not limited to developers, service managers, product owners and technical architects.

Achieving the expected benefits

If departments use the OpenAPI 3 standard, they would be consistent in the way they describe their APIs. Departments would be able to use OpenAPI 3 to automatically generate accurate and up to date API reference documentation irrespective of language. The specification will also enable departments to validate, version, maintain and update this generated documentation.

This could help increase adoption of these APIs across government by reducing time spent by departments in understanding different APIs. Departments will also benefit from the OpenAPI 3 tooling. For example, they will be able to send test requests to their API endpoints using different methods in the interactive API explorer.

When OpenAPI 3 may not be suitable

The OpenAPI 3 framework is a powerful tool for working with and describing RESTful APIs. However, departments must assess if OpenAPI 3 is the correct framework to document their APIs.

Firstly, OpenAPI 3 is for RESTful APIs only, and cannot describe SOAP APIs or APIs that use GRPC or GraphQL. Additionally, OpenAPI 3 covers the majority but not all possible styles of RESTful APIs.

Currently, OpenAPI 3 has a description of itself located at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema. The OpenAPI 3 machine-readable and verifiable JSON schema is still being finalised. This makes it harder to assess and verify if an API complies with the OpenAPI 3 specification. This could potentially lengthen the development time of an API written in OpenAPI 3 as it would be harder to spot and fix bugs and issues during development.

However, other validation tools exist. These assess APIs on non-schema criteria such as the API data and references. Some of these tools are located at https://openapi.tools/. Additionally, it must be noted that a JSON Schema validation does not guarantee compliance, because a JSON schema does not allow for validation of all use cases in the specification.

Departments should also assess what tooling is available for their chosen API specification. There are currently multiple OpenAPI 3 tools that enable users to, for example, validate their API (as mentioned above), integrate their API into web pages, or translate an OpenAPI 3 specification into another specification such as RAML. This tooling is regularly expanding, but is not fully comprehensive yet. Other API specifications also have tooling, for example RAML has multiple testing tools located at https://raml.org/developers/test-your-api. Departments should assess what tooling is most appropriate for their use case.

Other steps to achieving interoperability

This proposal is only concerned with promoting consistent and accurate API reference information across government. This is because the OpenAPI specification only covers reference information such as the API’s endpoints. Fully developed API documentation includes other information such as quick start guides, API keys, running a sample application, rate limits and many other subjects. Government departments should still write the non-reference parts of API documentation. This challenge does not include how government departments write their APIs (for example syntax, response format) or where those APIs live.

[PeterParslow]

For interest - and in support! - OS has agreed internally that our APIs should all have OpenAPI specifications, and we support adopting the current version.

Of course, that doesn't yet mean that we've created OpenAPI specs for all our APIs, but we're working on it!

[anjaneshbabu]

New to the group - would like to support the current process and welcome the proposal.

From where I am standing , the heritage/cultural sector is big on accelerating enablers for media exchange across systems - both internal and external. Particularly encouraged by the multipart file uploader which potentially facilitates the large media files.

[Lawrence-G]

The OpenAPI profile has been published on GOV.UK In the new recommend page of approved open standards Thank you, to everybody who contributed to this challenge