Skip to main content
search
Tag

specification

Oct 30
Love0

OpenAPI Initiative Newsletter – October 2024

By Blog

Welcome to the OpenAPI Initiative October 2024 Newsletter, our regular round-up of the latest stories from across the OpenAPI landscape.

Initiative News

Hot on the heels of the Arazzo Specification going to version 1.0.0, we are pleased to announce that Overlay is now at 1.0.0! If you’ve not heard of Overlay it is a specification created by our Overlay Special Interest Group (SIG) to provide a deterministic, repeatable mechanism for implementing automated updates to OpenAPI descriptions. Use cases for Overlay include document translation, configuration information updates, and implementing standards-based API design based on governance patterns. Please read me at the Overlay Specification repository.

The completion of Overlay version 1.0.0 shows that the OpenAPI Initiative has become more than just the OpenAPI Specification. Arazzo and Overlay help support the OpenAPI Specification in both alternative implementation patterns and through the API lifecycle. We’ll be covering this evolution of the OpenAPI Initiative on our blog very soon.

We are also planning our next OpenAPI Hangout session, which will be a LinkedIn Live event, and will this time cover education and training in the context of OpenAPI. Please keep an eye on our LinkedIn page for details and a link to the event.

Specification News

We are pleased to announce that our provisional members of the Technical Steering Committee (TSC) have now become permanent! Please join us in congratulating Ralf Handl, Mike Kistler, Lorna Mitchell, and Miguel Quintero on their promotion to become permanent members of the TSC. The TSC is an invaluable part of the OpenAPI Specification and helps lead and shape the development of OpenAPI.

Our 3.0.4 and 3.1.1 patch releases of the OpenAPI Specification are also complete!. 3.0.4 and 3.1.1 serve to provide clarifications for implementers across both 3.0 and 3.1 versions of the standard, to ensure consistency in readiness for OpenAPI 4.0 (“Moonwalk”).

The development of Moonwalk continues and has included revisiting the OpenAPI landscape and what each part of the ecosystem looks like. You can read more in our Moonwalk Discussions board. Please also take time to read Henry Andrew’s blog that describes the analysis of the OpenAPI tooling ecosystem, and presents both the architecture and relationships implicit in the ecosystem.

As always our specification meetings are open to anyone. If you want to join to listen in or contribute, you’ll find the meetings in the OAI calendar. We are always looking for new ideas and contributors, so please feel free to come along.

Events Round-up

Events season has kicked back into gear since our last newsletter, and we’ve been busy! Our OpenAPI track has been featured at both apidays London and apidays Melbourne, hosted by Erik Wilde.

In London, Erik was joined by Frank Kilcommins who went deep on Arazzo, Sohaib Tariq who talked about the APIMatic API Copilot, Lorna Mitchell who discussed API description pipelines, and Dr Gobe Hobona, who explained how OpenAPI is leveraged by the Open Geospatial Consortium to support the geospatial ecosystem.

Erik was joined in Melbourne by Adeel Ali who talked about how OpenAPI helps with code and portal generation, and Patrick Chiu who discussed the role of OpenAPI in federated API management. The wealth and breadth of topics show how the API ecosystem uses and embraces OpenAPI. The tracks are also extremely well attended, which is a testament to their value for apidays conference attendees.

The OpenAPI Initiative also appeared at the Nordic APIs Platform Summit, where Chris Wood and BGB chairperson Budha Bhattacharya hosted an OpenAPI Fundamentals workshop based on our Linux Foundation training course of the same name. We are looking to expand our in-person training opportunities in 2025, with the potential to deliver certification opportunities to the community.

Event Outlook

Our final dedicated OpenAPI track of 2024 will be at apidays Paris, 3rd – 5th December 2024. Apidays Paris is the flagship apidays event, and this year will cover many subjects including API lifecycle management, cloud-native infrastructure, GenAI, and GreenIT. OpenAPI is a major feature in any of these subjects, which is why our OpenAPI track is an important part of the apidays Paris experience.

Apidays Paris provides an opportunity for you to get involved. We are currently looking for speakers to join us on the OpenAPI track and share your stories about using OpenAPI in your organizations and industries. If you want to submit a proposal please go to our submission page to send us your idea, where you’ll also find topics we are particularly interested in hearing about. Erik and the team will be in touch to discuss your proposal and potentially move forward with it to appear on our track in Paris.

Finally…

That’s it for this newsletter. If you have any news you want to share with the OpenAPI community please get in touch by email or join the Outreach channel on Slack.

We also welcome suggestions on how we can improve this newsletter or bring you information that can help make the most of how you use specifications published by the OpenAPI Initiative. We are also looking for ways to highlight OpenAPI Initiative member contributions to the community. Please get in touch if you would like to work with us to tell your story.

Author: Chris Wood

Oct 25
Love1

Announcing OpenAPI Specification versions 3.0.4 and 3.1.1

By Blog

Hot on the heels of our Overlay 1.0.0 announcement, the OpenAPI Initiative is pleased to announce a patch release of the 3.0 and 3.1 OpenAPI Specifications!

In patch releases, no changes are made to the way that APIs are described, but the specification wording itself contains many updates, expansions, and clarifications where previously the points may have been unclear or not covered. Tooling that supports 3.1.0 is expected to work without problems on 3.1.1 since the patch releases does not contain structure changes.

Think of this release as the “Words Mean Things” edition!

Released versions

3.1.1 is the newest and recommended version of the OpenAPI Specification. If you are starting a new project today, or have the option to upgrade, this is your target version.

3.0.4 is an additional release on the 3.0 branch to incorporate the improved wording to the 3.0 branch of the specification where the changes applied there. It is expected that 3.0.4 will be the final release in the 3.0.x line.

Summary of changes

The releases include as many explanations, clarifications and expanded sections as we could manage, driven mostly by the questions and comments we get from the users and tools creators of the OpenAPI Specification. The highlights include a lot of new content to expand on existing content and reduce ambiguity. The sections regarding parameters, encoding and schemas have had significant updates and have been expanded to cover more cases. You will also find some security clarifications and a whole new “Security Considerations” section has been added.

Look out for additional appendices with some great explanations that support the additions to the main body of the specification. We added a great collection of new content sections and appendix entries about handling data including data types, serialization and encoding. In 3.1, there is more information about parsing documents and resolving references since the adoption of full JSON Schema compatibility.

The updates also strayed into distinctly “meta” areas, so we’ve also got:

  • Examples of using the example and examples fields.
  • Reference to a JSON Schema to represent the OpenAPI Specification schema.
  • Definitions for when something was undefined or implementation dependent.

Beyond the specification

In addition to the main specifications that you can always find at spec.openapis.org, there are a number of other resources that you may find helpful:

All of these resources are now linked from the relevant parts of the OpenAPI Specification.

We also updated the tooling that publishes the specification, changed the GitHub repository structure, cleaned up and reformatted all the Markdown content, and improved our workflow automation. These changes do not affect the specification but does make it a nicer place to be and hopefully makes the next release easier too.

Upgrade process

Most users and tool vendors should have no action to take, since the patch releases contain only wording changes or clarifications and no structure changes. That said, especially if you publish OpenAPI tools, take a look at the release notes on GitHub to check that there are no surprises!

Acknowledgements

So many contributors have contributed to this release, it’s not possible to name them all. If you suggested an idea, joined our regular calls to discuss the changes, opened or reviewed a pull request, or participated in any of the discussions about the changes, then we thank you! We had a LOT of help, and the new releases are very much improved for it (also the previous release was quite some time ago, a lot of people added to the project in the meantime).

Particular thanks goes to the Technical Steering Committee members who teamed up and shepherded the whole thing through, and to Henry Andrews whose counsel and hands-on help were a very welcome addition to the process.

Get involved

There are lots of ways to get involved with OpenAPI, and we like to hear from everyone who uses OpenAPI (or wants to)!

Authors: Lorna Mitchell, Henry Andrews

Oct 22
Love1

Announcing OpenAPI Overlay Specification 1.0.0

By Blog

The OpenAPI Initiative is proud to announce the publication of the OpenAPI Overlay Specification version 1.0.0.

The Overlay Specification is an auxiliary standard to complement the existing OpenAPI specification. An OpenAPI description lays out API operations, data structures, and additional metadata to describe the shape of an API. An Overlay lists a series of repeatable changes to make to a given OpenAPI description, giving a way to apply transformations to OpenAPI descriptions as part of your API workflows.

This specification has been an implementer’s draft for some time, so you may find that your OpenAPI tooling already has or is planning support for Overlays. If you are already using Overlays then you should not see any material changes between an older implementation and the version of the release version. The recent updates aimed to complete the wording and clarify the specification to make it suitable for a formal 1.0 release.

What is an Overlay?

An Overlay is a JSON or YAML file that follows the Overlay Specification and that contains a list of updates applied in the order they appear in the file. Updates might be to add a new value, overwrite an existing value, or remove something from an OpenAPI description.

The following code snippet provides an example of an Overlay encoded in YAML:

overlay: 1.0.0
info:
  title: Fix up API description
  version: 1.0.1
actions:
  - target: $.info
    update:
      title: Public-facing API title
      description: >-
        Description fields allow for longer explanations and support Markdown
        so that you can add links or formatting where it's useful.
  - target: $.paths['/secret'].get
    remove: true

The Overlay itself has high-level metadata in the overlay and info sections that follow the same semantics as an OpenAPI description and will be familiar to existing OpenAPI users. The actions array details each change to make to the OpenAPI, which is applied in order. In the first example above, the first action updates the info.title and info.description fields, while the second action removes the endpoint GET /secret.

A similar example that removes any Path Item that is not labeled to be published to customers, identified using a Specification Extension x-customer-facing, is shown in the following snippet:

overlay: 1.0.0
info:
  title: Fix up API description
  version: 1.0.1
actions:
  - target: "$.paths.*[?(@.x-customer-facing == false)]"
    remove: true

Both examples demonstrate the utility of Overlays, namely to make repeatable, deterministic updates to an OpenAPI description that can be automated throughout the OpenAPI toolchain. The means to apply automated updates is critical to supporting a robust API description pipeline, ensuring that your API community receives accurate and correct OpenAPI descriptions.

Overlay Use Cases

There are several pain points in OpenAPI workflows that an Overlay could be helpful for.

Improve Developer Experience

Your OpenAPI descriptions should be complete and ready for the target audience before publication. You can use an Overlay to add or improve the descriptions and examples that are provided in your OpenAPI descriptions. This is especially valuable where code is generated from a source that does not have a rich set of user-facing content already in place. Overlay provides a standard way to apply upgrades before publishing.

Filter API descriptions

You should remove restricted, deprecated or experimental endpoints before sharing an OpenAPI. If you have a situation where an API operation or even an individual parameter cannot be properly described in the OpenAPI description because the audience is restricted or internal, then an Overlay can be implemented to remove it to provide a “safe” version of the description. You can provide one parent OpenAPI description and use filtering to create reduced versions for multiple audiences as needed.

Translate API reference documentation

If you localize your documentation you can use Overlays to apply translations for the title, summary, and description properties and provide one OpenAPI description per target language. A repeatable translation option can help to keep the processes running quickly and easily. For APIs with global audiences, Overlay is especially valuable as repeatable translation work for APIs can be a tricky problem to solve, and often restricts how quickly your API can iterate.

Add Tool-specific Content

For tools such as OpenAPI gateways, AI consumers, or SDK code generators, additional content in your OpenAPI descriptions can help get the best results. You can use Overlay to add that data at a later stage if you either do not have control over the input OpenAPIs themselves or if you do not want to feed one tool’s metadata to all other tools. You can apply the Overlay to enhance the OpenAPI description immediately before sending it to the tool that needs the transformed version.

There are many more use cases than the ones we have listed. We are looking forward to hearing more about how you use Overlays in your own work.

Extending Overlays

The Overlay specification also includes an extends property so if one Overlay is specific to a single OpenAPI description, this optional field is used to indicate which one. The output of applying an Overlay to an OpenAPI description is … another OpenAPI description – so there are no restrictions on then applying another one!

An example of applying multiple separate Overlays to one API description could be where there’s an Overlay maintained by your technical writers that adds description fields for every operation, and another that makes all the examples of date properties update to a current date, so that all examples are always realistic and useful.

Similarly, one Overlay might be useful for multiple different OpenAPI descriptions, if the same transformation is useful for all.
Examples include applying the same license field to a series of OpenAPI descriptions, or adding an x-internal field on every path starting with /admin.

Next steps

To find out more about Overlay please checkout the following resources:

You can also get involved by following the GitHub repository for the Overlay Specification or join the #overlays channel on the OpenAPI Initiative slack. We look forward to seeing you there!

Close Menu