Diving into OpenAPI 3.1

In the past decade API’s have proliferated. Companies sought increased efficiency through automated business-to-business transaction processing using APIs; web-based companies created APIs to enable developers to integrate their data products into new processes; and new companies were created that pulled data from multiple external APIs and fused it into their own processing to produce unique web products that offered potential audiences a view of meshed data that wasn’t available elsewhere. The pandemic accelerated this trend, as people working from home were no longer able to easily and securely connect to the corporate intranet to accomplish their tasks.

As the number of available APIs mushroomed, problems arose:

  • Findability: a potential customer needs what your API offers, but how do they discover that your API exists?
  • Usability: when a potential customer discovers your API, how difficult is it for them to understand what has to be done in order to call the API?
  • Consistency: integrating a large number of APIs with unique organizational structures and formats is a burden for a development team.
  • Security: is your API sufficiently secure for a customer to feel safe using it; also, is your security sufficiently strong to prevent hacks into your core systems using your API as the entryway?

The problems that face companies that decide to produce one or more APIs are broad and complex. However, the magnitude of these problems is increasingly being noticed, and solutions to aspects of the problems APIs entail are in various stages of development.

OpenAPI Initiative

The OpenAPI Initiative (OAI) is addressing the problems of API usability and consistency. The OAI “was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor neutral description format.”

The end of that statement is important: the OAI is not a specification on how APIs should be constructed; rather, it is a language or schema that utilizes JSON or YAML to describe an API in a fixed format that is both human and machine readable.

It is not necessary to change an existing API in order to write an OpenAPI specification document for the API. As long as the API embeds generic structures that are common to most APIs, it will be possible to create an OAI document describing the API. This can then be published, making it available for cataloging and discovery by tools designed to read OpenAPI documents. However, since OpenAPI documents have their own structure, it’s possible that for some existing APIs (that may have unique structures), creating an OpenAPI document will not be possible.

The OpenAPI Initiative is supported by a large consortium of companies, including large global corporations and smaller companies that have an API-centric focus.

OpenAPI 3.1

The most recent OAI news is the OpenAPI Specification 3.1.0 Release. The new version highlights:

  • 100% compatibility with the latest draft (2020-12) of JSON Schema
  • new documentation to make it easier to understand the structure of the specification and its benefits

Marsh Gardiner, Product Manager, Google, and Technical Steering Committee, OpenAPI Initiative said: “Great care was taken in evolving to version 3.1.0 to ensure it is an incremental upgrade for existing users, while also making it an excellent candidate for immediate evaluation and adoption in corporate environments.”

“The mismatch between OpenAPI JSON Schema-like structures and JSON Schema itself has long been a problem for users and implementers. Full alignment of OpenAPI 3.1.0 with JSON Schema draft 2020-12 will not only save users much pain, but also ushers in a new standardised approach to schema extensions,” said Ben Hutton, JSON Schema project lead.

To assist developers who have been using OpenAPI 3.0, Phil Sturgeon, product manager, Stoplight, wrote the article Migrating from OpenAPI 3.0 to 3.1.0.

The full OpenAPI Version 3.1 Specification was released on 15 February 2021, and is available for review.


OpenAPI Version 3.1 represents a significant consolidation of methods for describing the structure of the vast majority of APIs using defined, well-structured human and machine readable JSON or YAML text. In subsequent posts, I’ll go further into the OpenAPI specification, discuss tools produced by the OAI community in support of the specification, provide example OpenAPI API specification documents, then move into the broad problem of API security.

–Kevin Farnham