UK Government Selects OpenAPI v3, Hacker News

      

Over the summer, the Open Standards Board received proposals for a standard and specification. Contributors suggested an open standard to make it easier for the government to publish and reuse data, and an open specification to promote the consistent and accurate description of RESTful APIs.

The Open Standards Board reviewed and approved both proposals and now recommends using the:

• RFC 4180 standard to publish tabular data
• OpenAPI 3 specification for RESTful API descriptions

Why the RFC 4180 standard

The comma separated values ​​(CSV) format is a popular way to exchange columns of numbers and text between software. CSV is used for publishing data tables on GOV.UK, often alongside a spreadsheet. The lack of a standard for CSV files can cause problems for people trying to reuse published data. This prompted achallenge on GitHubcalling for the standardization of CSV.

The challenge owner and contributors worked together to develop a profile ofRFC 4180, anInternet Engineering Task Force (IETF) specification, after extensive discussions on the GitHub page.

The IETF RFC 4180 is a simple document describing a standard format for CSV files. While the RFC leaves some items in the standard as optional, the profile selected by the challenge owner specifies how the standard should be used. For example, character encoding must be UTF-8 and a header row should be included with the data.

This standard allows the use of CSV files in a wide selection of software tools without editing them first. The consistent formatting makes government open data easier for people to use and saves data analysts ’time.

Describing RESTful APIs with OpenAPI 3

Another challenge was submitted to use theOpenAPI version 3 to describe RESTful APIs.The proposal was originally raised in 2016 but was deemed as too new, did not have enough supporting tools, and it was not clear if it would be supported by users.

The Open Standards Board reviewed this challenge again after the specification matured. The board did not mandate the specification as it’s not suitable for all types of APIs but has recommended its use.

OpenAPI 3 is important because it can help users to:

• generate accurate up to dateAPI reference documentation, no matter what programming language an API is written in
• validate, version, maintain and update this generated documentation
• use a consistent API description to help increase adoption of APIs across government by reducing time spent understanding different APIs

Before the Board’s decision to recommend OpenAPI 3, GDS technical writer Jon Glassman carried out further research to confirm:

• OpenAPI 3 was the most common way to describe RESTful APIs
• the tooling for OpenAPI 3 had continued to develop and evolve
• the majority of concerns raised previously were no longer valid and people were happy to recommend OpenAPI 3

There aremultiple OpenAPI toolsavailable. For example, you can send test requests to your API endpoints using different methods in the interactive API explorer.

The aim is to encourage API teams to produce definition files in a format that is readable by machines and language-agnostic. No matter what language developers are working in, they will be able to understand the API and what it can do.

It’s important to remember that this specification only applies todescribing APIs and generating API reference information. Complete API documentation also covers information like quick start guides and API keys. This is covered by ourAPI guidance.

How to propose an open standard

If you know of an issue where an open standard for cross-government use will make things better you can submit a proposal.

1. Visit our GitHub issues page.
2. Suggest a standard or specification that fits a user need or open a challenge to discover which standards to use in a particular situation.
3. The community will assess and comment on the standard’s openness, applicability and maturity.
4. You will then need to put forward a proposal to the Open Standards Board, which will make the final decision.

If you’d like to get in touch with any questions about open standards you can drop the team a note on[email protected]or leave a comment below.