 |
VOOZH | about |
|
VOOZH | about |
We’re so glad you’re here. You can expect all the best TNS content to arrive Monday through Friday to keep you on top of the news and at the top of your game.
Check your inbox for a confirmation email where you can adjust your preferences and even join additional groups.
Follow TNS on your favorite social media networks.
Become a TNS follower on LinkedIn.
Check out the latest featured and trending stories while you wait for your first TNS newsletter.
OpenAPI is a standard way to describe your API for both human and machine audiences. From an OpenAPI description, API producers can check their API for compliance, run automated testing tools for their API and publish instant documentation. API consumers can also use these files to power their own integrations.
While the OpenAPI standard itself isn’t new, recent months have seen some updates from the OpenAPI Initiative, including an update to the OpenAPI specification and the publication of two new standards.
The OpenAPI Overlay Specification, released in October, describes a series of edits to apply to an OpenAPI description, making it easier to repeat the same updates to a description. The almost-as-new OpenAPI Arazzo Specification, released in May, provides a mechanism for outlining a sequence of API calls and how a process involving multiple API operations is performed.
As a patch release, the 3.1.1 version of the specification, released in October, received only minor updates. But as the first updates since early 2021, those updates do show that the project is alive and well. Many of the changes were also included in an update to OpenAPI 3.0, which is now at version 3.0.4.
Most of the changes in these patch versions are improvements to the wording in the specification document, clarifying a lot of ambiguous clauses, and adding examples. Some sections were refactored into five new appendices, and a new introductory text was added.
Parts of the document were expanded and re-worded to address common issues or questions from the community and provide clearer guidance to both tooling and end-user communities. Some of the areas around document parsing, data types and serialization, in particular, have benefited from attention.
Alongside the changes to the specification itself, the published JSON Schema representations also received some updates.
The Overlay Specification has been in draft for some time, and had a formal release in October. An Overlay is a JSON or YAML document that describes a series of actions to perform on an OpenAPI document.
Some good use cases for an Overlay could be:
An Overlay can target a specific OpenAPI description or be used against any/many OpenAPI descriptions. The following example Overlay adds a license to an OpenAPI description:
While “design-first” is considered best practice for API development, many projects use a “code-first” approach and create an OpenAPI description automatically from the code for the API application. Working this way makes it difficult to improve the OpenAPI description because it gets regenerated when the code changes. Overlays allow repeatable changes to be made to the regenerated OpenAPI.
Multiple API tools include production-ready support for working with Overlays. Try the CLI tools from Speakeasy or Bump.sh, or visit the OpenAPI Overlays repository for more options.
As stated previously, the Arazzo specification was released last May, but this January saw a patch release (the most minor update) for the spec, to version 1.0.1. An Arazzo description is a JSON or YAML document detailing sequences of API calls, chaining them together into more complex workflows.
For our modern applications, where operations are more involved than making a single API call, Arazzo helps to connect the dots in order to draw the bigger picture.
An Arazzo document describes one or more workflows, each containing a series of steps. Each step is an API call and can refer to an existing OpenAPI document for the details of the call. Each step includes criteria for success; the next step is only executed if the criteria is met.
Representing the more complex flows is great for creating interactive documentation to walk users through the steps, generating SDKs that can perform multiple API calls as a single function, or testing realistic API workflows.
Tooling for Arazzo is in its early stages, but there are some great examples in the Arazzo specification repository, which serve as a good starting point for anyone who wants to use the new format. Both Spectral and Redocly CLI have also added Arazzo support to their linting tools, which is a big boost to getting to know and use the format.
Most of the API tool providers have Arazzo on their roadmaps, with tools for documenting and testing API workflows, so this is a “one to watch” topic for 2025.
OpenAPI is an active project with big plans. Next on the agenda for the main OpenAPI specification is a 3.2 release, expected over the coming months. Version 3.2 will include updates to security schemes, expanded tags functionality and other improvements.
Currently in the early planning stages is the OpenAPI 4.0 project, codenamed “Moonwalk.” That project will be one to watch.
OpenAPI specifications are open standards and the projects to develop them are also open and welcome to contributors and spectators alike. Check out the project website to find out about the repositories, open meetings and Slack community.
