Skip to main content
search
Category

Blog

Feb 20
Love0

OpenAPI Community Heroes – Erik Wilde

By Blog

Welcome to the next installment of our series of posts on people we consider to be heroes of the OpenAPI community. These people go above and beyond to contribute to the OpenAPI Initiative specifications, Special Interest Groups (SIG), or across the OpenAPI Initiative (OAI).

Our next Community Hero is Erik Wilde. Erik is an API industry expert and OAI Ambassador, and is responsible for the OAI tracks that have been a feature of the API events landscape in 2023 and 2024, with more to come in 2025. Erik has a background in research and academia, having held the roles of Associate Adjunct Professor and Assistant Professor at Berkley. He has contributed to many publications, patents, and standards, and worked with various industries and sectors, such as healthcare, education, finance, and government.

Erik filled us in on why he is involved in the OAI and his views on the role of standards in the industry.

What drives your interest and involvement in the OpenAPI Specification?

OpenAPI is one of the fundamental building blocks of today’s digital economy. It’s just a minor exaggeration to say that 100% of organizations today depend on OpenAPI in some place of their IT landscape to be able to do what they do.

Standards sometimes get a bad reputation as constraining things too much. And of course they do constrain things and there also are standards out there which possibly could have been designed better. But the important aspect is that standards create real value and they do so because people agree that using them is better than not using them.

OpenAPI has become the dominant standard for API descriptions and is effectively powering today’s global digital landscape. It’s thrilling to be part of that movement, and it is rewarding to try to help with improving the standard itself and improving the way how people learn about the standard and how to use it. We have ambitious goals for the OpenAPI Initiative to increase our visibility and make it easier for people to learn and adopt OpenAPI. I am optimistic that 2025 will change a fair bit how OAI is operating and how we engage with and help the global API community.

What do you consider to be your most significant personal contribution to the development of OpenAPI?

Right now it is probably the visibility and community around OpenAPI. I have been organizing OAI Tracks at various conferences for almost two years now. It’s always rewarding and interesting to see the many different contributions and ways how organizations are using OpenAPI.

OAI has an excellent technical arm that makes sure that OpenAPI remains a technically sound and well-designed specification. What we currently lack is a better connection with our community of OpenAPI users.

On the one hand we need that to make sure that more people are learning what OpenAPI is and how to use it. We also want more people to read our case studies and reports (planned for 2025!) so that they better understand what it takes to use OpenAPI well.

But on the other hand we also need more and better feedback from the community. What are the features people find most useful? What are features that seem to introduce complications? What are features that are missing? And what does the tool landscape out there actually implement, which brings us to the surprisingly difficult question to decide what “implementing OpenAPI” really means (which is a fascinating topic in itself and another major 2025 activity for OAI).

I think we need a larger base and better visibility in the community as a necessary step to better plan how to evolve the specification in a way that’s most useful for its users.

The OpenAPI Initiative is now a multi-specification organisation. How will the project change now that we are delivering more specifications to the API community?

Quite a bit of that is terminology and branding. We have a rather unfortunate name now that we’re not just managing the OpenAPI specification. We’ll be able to work with it, but we need to reassess our branding and things like our information architecture in general.

Our website is currently undergoing a major analysis and redesign and hopefully we will end this year with a prettier, easier navigable, and easier manageable website. One part of it is just improving things that we’ve known for a while, but taking the multi-specification aspect into account is one of the major reasons for the redesign.

What’s great is that our two new specifications are fitting into rather specific and easily explainable gaps. This means that our story of how we support the API landscape becomes more complete and overall a more convincing story. It also means that we can tell better stories of how tools and tool chains can be used because there are interoperable descriptions of various aspects throughout the API lifecycle.

In the end, being a multi-specification organization has increased the potential of OAI as a unique provider of solutions in the API space. But it also has made it a bit more challenging for us to tell our story and the story of our specifications. What do you see in the future for the OpenAPI Specification?

One of the important tasks going forward is to better understand if and how could be improved to better support AI scenarios. It might be as simple as adding some guidance around API design and how to best write the OpenAPI description for AI consumers. This is particularly interesting for AI agents which probably would want to discover higher-level information on how to use an API, for example in an Arazzo workflow description.

But we may also see that AI scenarios are requiring updates to OpenAPI, to other OAI specifications, or maybe will need entirely new specifications. We’re only at the beginning of understanding the potential and impact of AI scenarios, but I am sure that a year from now we will have a better idea about how to make OpenAPI more AI-friendly.

Personally, I think the current version has proven to provide enough value for us to invest more into explaining that value and making it easier to realize. It’s not OAI’s goal to turn into an API consulting firm, but given our unique position in the API landscape we can provide trainings, case studies, and reports with more authority than most other entities out there, and it would help our users if we did more of that.

What other standards developments do you consider particularly significant for the API economy?

First and foremost our “sister specifications” that are also part of the Linux Foundation have to be mentioned: AsyncAPI and GraphQL. And then there’s of course gRPC which is not part of the Linux Foundation but still can be considered an open standard. So these are the big ones complementing OpenAPI when it comes to providing open and established technologies for various API styles.

When it comes to OpenAPI itself then of course we have standards like JSON Schema, OpenID, and OpenID Connect (OIC), which are very central to using OpenAPI APIs and need to be treated as an almost integral part of OpenAPI by now.

What we may also see is some variant of a catalog format, where it is possible to advertise API catalogs and to describe APIs in those catalogs with machine-readable API descriptions and other metadata that may be helpful to work with the API. Since we do see more and more scenarios where scaling the API practices is one of the challenges, we may see such a catalog format emerging as a way to more easily share APIs.

Should more people get involved in developing the OpenAPI Initiative specifications and why?

Yes, it would be great to see more people getting involved with OAI. We want to play our part by creating more useful content going forward, in particular in terms of training, case studies, and reports. These things will help OpenAPI users, but the more we can create these based on feedback, the more likely we will create the ones that have the most impact.

In my mind, APIs still are too often treated as a mere side-effect of having an IT landscape where components need to be connected. Of course we need APIs on this very basic level, but in many organizations there is a lot of unrealized potential because APIs are not managed strategically. We still need to be better at telling the story of API representing business capabilities, the option value that they bring to an organization, and the steps it takes to create the right APIs and to create them the right way.

We’re only getting started with Getting APIs to Work at OAI, and given that we have big plans for 2025 this is the ideal time to join the movement, start engaging with OAI, and help us to better understand how we can better help you and the API community in general!

Author: Erik Wilde

Feb 05
Love0

Moonwalk – 2025 update

By Blog

Just over a year ago, we established a Special Interest Group (SIG) to explore how to evolve the OpenAPI Specification. We called this effort "Moonwalk," and we began by declaring our intentions in an initial Moonwalk blog post. Since then, a group of committed contributors have met on Tuesdays at 9am Pacific to discuss these topics.

As we look to build momentum in 2025, we wanted to recap our progress so far. We added one more principle (#4 below) to the original five:

  1. Semantics: Semantics provide purpose, whether the consumer is a human or an AI.
  2. Signatures: An API operation is identifiable by its signature, which can be based on any aspect of HTTP mechanics.
  3. Inclusion: Moonwalk aspires to describe all HTTP-based APIs while remaining neutral regarding any specific design debate.
  4. Foundational Interfaces: Reduce the complexity for tooling authors by establishing standardized interfaces for parsing API description documents and defining consistent methods for expressing API structural semantics.
  5. Separation of Concerns: Modularization will keep the scope of Moonwalk manageable with loose coupling among concerns such as HTTP interfaces ("API shapes"), deployment configuration, and content schema formats.
  6. Mechanical Upgrading: An automated upgrade process from 3.x to 4.0 will be developed as part of the Moonwalk effort.

The new Foundational Interfaces principle would not have been possible without the work of Henry Andrews. His efforts to understand the OpenAPI compliance space led to a re-framing of why this is so difficult to achieve today and provided insights into what might need to change in order to make compliance tooling possible and more (related post).

Another area of keen interest has been how semantics (principle #1) and signatures (principle #2) often intersect. Signatures represent a way to organize the functionality of an API, while semantics describe the purpose or meaning behind that functionality. As Large Language Models (LLMs) continue to reshape how people interact with technology, an OpenAPI description becomes even more useful for connecting these two parts.

Some insights from SIG discussions have helped to evolve the 3.x release line, as they were backwards compatible. Examples include enhancements to tags and the ability to make documents self-identifying to make it easier to support "external" references.

Last fall, two tooling authors joined to discuss their experiences in practice. Yusuke Tsutsumi spoke about the aep.dev project, and Dave Shanley discussed The Doctor and related tools. These conversations were invaluable, and we hope to learn from others. Please comment on our agenda discussions if you are interested in talking about your experience as a tooling author using OAS.

The timeline for Moonwalk reaching a 4.0.0 release remains open-ended (as of this post in early 2025). The foundational progress made in 2024 would not have been possible without the work and enthusiasm of the regular contributors.

If you find these topics interesting, we hope you’ll join us in 2025! Get involved by:

  • Joining our channel on Slack.
  • Attending the weekly SIG meeting. See the weekly agenda posts in GitHub Announcements for more details.

We look forward to seeing you!

Author: Marsh Gardiner

Jan 24
Love0

Announcing Arazzo Specification version 1.0.1

By Blog

In 2024, the OpenAPI Initiative set a high bar for activity with the release of new specifications like Arazzo 1.0.0 and Overlay 1.0.0, along with two important patch versions of the OpenAPI Specification: 3.1.1 and 3.0.4. Today, we’re excited to kick off 2025 on a strong note by announcing the release of Arazzo Specification version 1.0.1!

This 1.0.1 patch release introduces updates, clarifications, and expansions that refine the specification without altering its core functionality. While the way workflows are described in Arazzo remains unchanged, this release addresses areas where greater clarity was needed, improves examples for implementers, and corrects minor inaccuracies (as is typical with any initial 1.0.0 release).

Importantly, tooling built for Arazzo 1.0.0 will remain fully compatible with 1.0.1, as the patch release does not include any structural changes. This reflects our commitment to maintaining backward compatibility and supporting frequent, iterative improvements for the specification.

If you’re starting a new project or have the flexibility to upgrade, we highly recommend targeting Arazzo 1.0.1 as your version of choice!

Summary of changes

The 1.0.1 release brings important clarifications, improved and corrected examples, and addresses minor inaccuracies in the initial 1.0.0 release. In addition, we’ve introduced a non-authoritative JSON Schema representation of the Arazzo Specification, making it easier for implementers to validate documents programmatically.

Here’s a quick summary of the notable changes in Arazzo 1.0.1:

  • JSON Schema added for the Arazzo Specification 1.0.x.
  • JSON Schema test suite for validation and compliance.
  • Clarified the allowed types for the retryAfter fixed field within the Failure Action object.
  • Improved clarity around the use of workflowId across the Step, Success Action, and Failure Action objects.
  • Adopted RFC 9110 as the reference for Header Field guidance.
  • Adopted RFC 9110 for payload (or request content) guidance.
  • Fixed inaccuracies and typos in field descriptions within the Step Object and Parameter Object.
  • Removed redundant references to event-based message properties from the Runtime Expressions.

Upgrade process

For most users and tool vendors, no action is required—this patch release introduces only wording changes, clarifications, and corrections, with no structural changes to the specification.

That said, if you publish Arazzo tools or maintain workflows that rely on the specification, we recommend reviewing the release notes on
GitHub to ensure everything aligns with your expectations. While the update should be seamless, it’s always a good idea to double-check for any changes relevant to your implementation.

Looking ahead

As noted earlier, we anticipate relatively frequent updates to the Arazzo specification. To ensure smooth adoption, we recommend that tooling makers avoid locking into a specific patch version of the specification, as all patch releases will remain backward compatible.

Looking ahead, we’re already making significant progress on the upcoming Arazzo 1.1.0 minor release. The primary focus of this release is to introduce support for AsyncAPI, enabling workflows to span APIs that leverage both HTTP and event-driven protocols. This exciting development will expand Arazzo’s capabilities, making it a more versatile and comprehensive solution for modern API ecosystems.

Timeline of Arazzo releases, showing version 1.0.1 at January 2025 and the next release at version 1.1.0 scheduled for mid-2025

Timeline of Arazzo Specification Releases

Acknowledgements

This release would not have been possible without the contributions of our vibrant, community-driven ecosystem. The active engagement and stewardship shown by our contributors continue to inspire and drive the evolution of Arazzo. While it’s not possible to name everyone individually, we want to extend our sincere thanks to everyone who has suggested an idea, raised a constructive issue, opened or reviewed a pull request, or participated in our regular calls or discussions. Your efforts have been invaluable, and we deeply appreciate your support and commitment!

We’d like to give particular thanks to the Arazzo Specification editors, who have worked tirelessly to drive, coordinate, and prepare releases for the specification. A special word of gratitude goes to Jeremy Fiel for his excellent work in providing the JSON Schema for Arazzo, and to Ralf Handl from the OpenAPI Initiative Technical Steering Committee, for his hands-on support and invaluable counsel in improving the infrastructural setup around the specification repository.

Thank you all for making Arazzo 1.0.1 a reality!

Getting involved

There are many ways to get involved with Arazzo and the broader OpenAPI Initiative, and we’d like to hear from everyone who uses Arazzo (or wants to)!

Author: Frank Kilcommins

Dec 23
Love0

OpenAPI Initiative Newsletter – December 2024

By Blog

Welcome to our December 2024 newsletter, the final OpenAPI Initiative roundup of the year! Our newsletter brings you initiative news, details of new versions of our specifications, and information on events and educational resources.

Initiative News

In 2024 the OpenAPI Initiative (OAI) grew from one specification to three, with two new specifications added.

In May Arazzo version 1.0 was released. If you’ve not heard of Arazzo, it is a description language for describing sequences of API calls, and supports passing of dynamic data between steps. Arazzo is an attempt for API providers to help describe such sequences in an increasingly complex API-driven world, in order to reduce onboarding time for developers implementing flows and reduce cost and complexity.

October also saw the release of the Overlay Specification at version 1.0. Overlay is a specification for describing updates to an OpenAPI description document in a consistent, deterministic way. Overlay helps API providers update their OpenAPI descriptions through the API lifecycle, and supports building pipelines for API descriptions, supporting automation. Overlay and automation can help organizations manage the publication of their OpenAPI descriptions more accurately, with increased quality, at lower cost.

Finally the OpenAPI Specification was also uplifted to versions 3.0.4 and 3.1.1. Being patch releases these releases did not introduce new features, but sought to clarify features of the 3.0 and 3.1 specifications with a significant amount of new and revised supporting guidance added to the specifications. Updates include extensive guidance on modeling parameters, headers, and form data, handling URL percent-encoding, parsing documents and resolving references, and choosing which fields to use for examples. The specification now also link to the extension registries, the JSON Schema for OpenAPI Description documents, and the Learn OpenAPI site.

Looking ahead to 2025 there are already plans afoot for new versions of the OpenAPI Specification.

At the end of 2023 we announced project Moonwalk with an ambitious goal of shipping a major release by the end of 2024. While v4.0 of the OpenAPI Specification is still some way off, we have learned a great deal and are now planning v3.2 and v3.3 as incremental steps towards v4.0 that will be fully backwards-compatible with v3.1.

Version 3.2 is intended to deliver a small set of new features quickly in 2025. Two of these features, (hierarchical, categorizable tags and self-identifying documents, which take much of the pain out of external references) emerged from the Moonwalk effort. While the scope will no doubt evolve, other features under consideration include streaming JSON formats, additional HTTP methods, device authorization flow, and links to OAuth authorization server metadata. This sounds like a lot, but aside from the changes with tags, most of these features are straightforward.

Work on v3.3 will start immediately after 3.2, and will deliver bigger ideas from Moonwalk. Two areas under consideration – a major streamlining of parameter, header, and form data modeling, and expanded OpenID Connect features – were 3.2 proposals that could not be done quickly. A v3.3 release, which has no date at this time, lets us take incorporate more Moonwalk ideas to solve these problems thoroughly.

As for v4.0 itself, the Moonwalk effort motivated us to understand how the OAS is implemented, and how to ensure that the specification truly represents the needs of the community. Henry Andrews summarizes this introspection in his blog, where he lays out an idealized architecture. Moonwalk will continue to progress in 2025.

The work on new specifications and specification releases, the increased adoption of 3.1, and the significant interest in Arazzo and Overlay all bodes well for another busy year in 2025. You can read more about OAI moving from one to three specifications and plans for next year in our blog post covering the changes in the initiative and what will come next in our evolution.

Events

2024 was another great year for events, with our continued partnership with apidays plus an appearance at the JAX Mainz Conference. The OAI track appeared at apidays Singapore, New York, Helsinki, London, Australia, and finally Paris, with a huge array of different talks ranging from introductions to Arazzo, views on how OpenAPI helps with API governance, and the role of OpenAPI in the geospatial ecosystem. The range of talks, together with generally packed conference rooms, are indicators of both the health and interest in the OpenAPI ecosystem, and in the strategic value of openness and open standards in general.

Looking ahead to 2025, we already have an OAI-supported event in the train at DeveloperWeek, where Erik Wilde and Frank Kilcommins will be hosting the first OAI track of the year. Our OAI tracks have been features of apidays for the last two years, but DeveloperWeek brings the OAI to a large conference audience that is not dedicated to APIs. Broadening our reach and gaining the interest of communities outside the immediate API space will help widen the opportunity to attract new members who already use the OpenAPI Specification without even knowing it.

Outside the OAI tracks we also have TSC member Lorna Mitchell presenting at FOSDEM 2025 with an overview of the aforementioned expansion of OAI into three specifications. If you are planning or have a talk lined up on any aspect of OAI in 2025, let us know! We’d be happy to include it in the newsletter.

One other initiative we have started this year is our OpenAPI Hangouts, where members of the OAI community come together to discuss aspects of the specifications in a webinar style format, broadcast on LinkedIn and YouTube. We plan to expand these in 2025, covering more topics and engaging with more community members.

Education and Training

We’ve also taken steps in 2024 in education and training, with some improvements and new initiatives designed to help the understanding of our specifications in the community.

Our Learning site continues to develop, with valuable resources for explaining OpenAPI in a narrative format. The site includes great resources that include a detailed walkthrough of references, examples of OpenAPI descriptions sourced from the community, and details from new specifications like Overlay.

Alongside our learning site, in 2024 we also created our OpenAPI Fundamentals course, an online training course provided at Linux Foundation Training to increase awareness of the background, basic structure, and approaches to using the OpenAPI Specification. The course is available for free and provides a badge of completion.

We’ve also provided a number of in-person training courses, first at the Nordic APIs Platform Summit and then at apidays Paris. While participation in terms of number of attendees for these courses was mixed, they represented an important step in allowing us to investigate how we can better support the community for training and learning. We’ll continue to look for opportunities to support the community through in-person training in 2025, starting with a full-day workshop about “Practical API Management with OpenAPI” at DeveloperWeek in February 2025.

Finally

That’s it for this newsletter, and 2024! We’ve achieved so much this year, and that is down to our great teams of volunteers who support the development of our standards. Thank you so much to our community and all the contributors who bring our specifications to life. Happy holidays everyone!

As ever, we 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 on the Outreach channel on Slack if you would like to work with us to tell your story.

Contributors: Chris Wood, Henry Andrews, Erik Wilde, Jeremy Fiel

Dec 05
Love0

Evolving OpenAPI in a Multi-Specification Initiative

By Blog

When people say “OpenAPI”, they are usually referring to the OpenAPI Specification, the API description language that helps us publish and consume APIs. The OpenAPI Specification is at the center of how the API community describes the shape of an API, allowing it to be readily understood.

However, you may not realize that the OpenAPI Initiative (OAI) has expanded beyond the core OpenAPI Specification. The needs of the API community have grown alongside the continued increase in scale of the API economy, and the community needs are reflected in the evolution of OAI to a multi-specification project. Our view of the world at the end of 2024 includes some significant developments over the last 12 months, with an equally exciting 2025 ahead. The OAI now incorporates the following projects:

  • OpenAPI Specification.
  • Arazzo Specification.
  • Overlay Specification.
  • OAS Comply.
  • Special Interest Groups (SIGs).

The tools, specifications, and groups that comprise the OAI project provide an increasingly large footprint of standards in the API economy. Their relationships are summarized in the diagram below, which shows how each tool, specification, or group fits into the OpenAPI ecosystem.

The specifications and tools that comprise the OpenAPI Initiative

Each of these provides features and functions important to the API community.

OpenAPI Specification

The OpenAPI Specification is the center of the OAI and the focus of our efforts to support the API community. OpenAPI is the most widely used API description language in the API ecosystem, with arguably the longest legacy, and supports the publication and consumption of an innumerable number of APIs throughout the API lifecycle.

The OpenAPI Specification is undergoing active development with support from dedicated volunteers, with a new major version coming soon focused on the semantic improvement of the specification and supporting AI use cases. The OAI is constantly evaluating how we can improve the development of the standard, and provide support for tooling makers who are implementing the specification.

OpenAPI is currently at version 3.1.1, with multiple versions planned to harmonize the features of the Specification in readiness for version 4.0.0, our next major version codenamed “Moonwalk”. You can read more about version 3.1.1 on our standards site and discover the goals of Moonwalk on our blog. We also released version 3.0.4 in 2024, again in an effort to harmonize guidance across different versions.

Arazzo Specification

The OpenAPI Specification was created to describe a single API and its supported operations. The API ecosystem has, however, grown significantly more complex as it has expanded, with a need to invoke multiple API operations across different API providers to complete a business operation. This growth in the interdependency of API operations has created a need for sequences of API calls to be described programmatically, which is why the Workflows Special Interest Group created the Arazzo Specification.

Arazzo is a description language that can reference multiple APIs, each described with an OpenAPI description or another Arazzo description, that provides API consumers with a rich view of complex, multistep workflows. Arazzo supports describing dynamic values, allowing API providers or API marketplaces to indicate how API operations relate to each other and the output and inputs that can be carried between each step. When supported by appropriate tooling this can significantly accelerate implementation time for API consumers and ensure they can handle sequences of API requests more accurately.

Arazzo is currently at version 1.0.0. You can read more about the Specification on our standards website.

Overlay Specification

The OpenAPI and Arazzo Specifications provide the backbone of the OAI, with description languages aimed at supporting use cases across the API ecosystem. OAI is also creating complementary specifications that help API providers and consumers publish and consistently work with OpenAPI descriptions.

An example of these efforts is the Overlay Specification, which is now at version 1.0.0. The Overlay Specification is intended to provide a consistent and deterministic way of applying updates to an OpenAPI description document. Example use cases include supporting multi-language API descriptions by using Overlays to contain language translations and including configuration information for different deployment environments in an OpenAPI description document.

OAS Comply

OAS Comply is an effort to develop tools to support tooling makers in implementing the OpenAPI Specification, with the potential to expand in the future to include the Arazzo Specification. The OASComply project was started in 2023 and was instrumental in understanding where the 3.0 and 3.1 specifications needed clarification.

The discoveries provided by OASComply motivated much of the work in the Open Specification 3.0.4 and 3.1.1 releases, as well as making compliance testability a major focus for Moonwalk. OASComply itself is on hold while we proceed with Moonwalk and figure out how compliance testability work might fit into our version 3 standards.

Special Interest Groups

Finally, OAI has Special Interest Groups that are focal points in evolving specific use cases across industries, verticals, or technology requirements. SIGs are an important means for channeling support for new ideas and initiatives, and it speaks volumes that the efforts to create Arazzo, Overlay, and Moonwalk are focused through SIGs.

The Future of the OpenAPI Initiative

The evolution of the OpenAPI Initiative has been largely organic and relied upon the endeavors of many dedicated volunteers. The members of the OpenAPI community have investigated, researched, discussed, and authored for thousands of hours to reach this point in the evolution of the OpenAPI Initiative.

Our next steps as an organization include:

  • Producing new versions of OpenAPI, including our next major version.
  • Maturing Arazzo and Overlay and helping tooling makers to support the specifications.
  • Expanding our support for both OpenAPI members and the community with investments in training, education, and certification.

If you are interested in helping develop the most important API description language on the Internet there is a huge opportunity for you. Join our Slack community to find out more.

Author: Chris Wood

Dec 04
Love0

AVAP Framework has just joined OpenAPI as a member!

By Blog

AVAP Framework has just joined OpenAPI as a member!

We are thrilled to announce that AVAP Framework, a cutting-edge API Lifecycle Management Platform, has officially joined the OpenAPI Initiative (OAI) as a proud member! This milestone reflects our commitment to innovation, collaboration, and advancing open standards in the API ecosystem.

What Is AVAP Framework?

AVAP Framework is a comprehensive suite of tools and services designed to streamline the entire API lifecycle—from design and development to deployment, maintenance, and beyond. At its heart is AVAP (Advanced Virtual API Programming), a specialized programming language tailored for creating virtual APIs that adapt seamlessly to evolving business and technology needs.

Central to AVAP Framework is Brunix, our AI-powered engine. Brunix optimizes processes, predicts solutions, and ensures that APIs are scalable, secure, and efficient across diverse environments. AVAP Framework’s universal compatibility ensures seamless integration with other technologies, enabling businesses to build flexible, resource-efficient, and future-ready APIs.

https://www.avapframework.com/ 

By joining the OpenAPI Initiative, AVAP Framework is aligning with the industry’s leading community focused on developing and promoting open standards for API design. Through this collaboration, we aim to contribute our expertise in virtual API programming, AI-driven innovations, and API lifecycle management to the evolution of the OpenAPI Specification (OAS).

Raúl Nogales, Founder & CEO of AVAP, will serve as our representative in the OAI. With his extensive experience in API innovation and technology, we are confident that AVAP Framework will add significant value to the OpenAPI ecosystem.

OpenAPI Resources

Want to become a member of the OpenAPI Initiative? Find more information here: https://www.openapis.org/membership/join 

To learn more about participating in the evolution of the OpenAPI Specification: https://www.openapis.org/participate/how-to-contribute

About the OpenAPI Initiative

The OpenAPI Initiative (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 OpenAPI Specification was originally based on the Swagger Specification, donated by SmartBear Software. To get involved with the OpenAPI Initiative, please visit https://www.openapis.org

About Linux Foundation

Founded in 2000, the Linux Foundation is supported by more than 1,000 members and is the world’s leading home for collaboration on open source software, open standards, open data, and open hardware. Linux Foundation projects like Linux, Kubernetes, Node.js and more are considered critical to the development of the world’s most important infrastructure. Its development methodology leverages established best practices and addresses the needs of contributors, users and solution providers to create sustainable models for open collaboration. For more information, please visit us at linuxfoundation.org.

Nov 29
Love0

OpenAPI Community Heroes – Karen Etheridge

By Blog

Welcome to the next installment of our series of posts on people we consider to be heroes of the OpenAPI community. These people go above and beyond to contribute to the OpenAPI Specification (OAS), Special Interest Groups (SIG), or across the OpenAPI Initiative.

Our next Community Hero is Karen Etheridge. Karen is a regular OpenAPI Specification contributor and describes herself as a “general busybody”. Karen told us about what drives her involvement in OpenAPI and what she hopes to see in Moonwalk.

What drives your interest and involvement in the OpenAPI Specification?

As a long-time backend software developer, I’ve worked with HTTP/REST APIs in several projects. A few jobs ago, we started defining our APIs with internally-developed code to use hooks in the dispatch process to perform data validation; as I pulled these data definitions out into formalized JSON Schemas, I discovered that the ecosystem for JSON Schema validation was incomplete, so I published my work to open source, as JSON-Schema-Modern.

A few years ago I was invited to join the Technical Steering Committee for the JSON Schema specification (json-schema.org), where I helped edit the latest release, draft2020-12, and where we’re now working on putting together revisions for the next release.

As part of my work in a later job, I moved into the OpenAPI space and built a new implementation of the OpenAPI v3.1 specification to perform validation of HTTP requests and responses, publishing that as OpenAPI-Modern. As I worked through this implementation I had many questions and observations about the spec, so this naturally led me to talking to the OpenAPI teams and community; shortly after, I began submiting improvements to the specification itself, and was subsequently pulled into a reviewer team for the specification and schemas. No good deed goes unpunished! 🙂 And now, this autumn, we’ve just gotten versions 3.0.4 and 3.1.1 out the door, and are now talking about changes for the upcoming 3.2 and 4.0 versions!

What do you see as the most exciting proposed features of version 4 of OpenAPI?

A lot of OpenAPI 4.0, codenamed Moonwalk, is still up in the air right now, so now is a perfect time for people to jump in with their opinions and requests! We’re working through the way requests and responses are expressed in OpenAPI and thinking about whether the current “shape” makes sense, and what modifications we need to make tooling easier. We’ve been throwing around the terms “ontology” and “taxonomy” a bit, and thinking about what these concepts mean for OpenAPI descriptions.

One thing that has come up regarding the current document structure is the oddity between expression of request parameters in a list (with the “name” property adjacent to all other properties), and response parameters as an object (with the “name” as the property name, one level above all other properties). Expressing parameters (such as request headers) in a list doesn’t really make sense, because HTTP headers don’t have a natural order, but also it’s convenient to group all header properties together, rather than having the “name” be at a different level. So we haven’t quite yet worked out what to do here.

One thing on my radar that I want to address in Moonwalk is the way multipart requests and responses are expressed in OpenAPI — the way the structure is described in the HTTP RFCs doesn’t really match how the current OpenAPI specification models them, so I think there are some improvements to be made there. They’d be backwards-incompatible, so these changes would have to be in version 4, not 3.2.

What do you see in the future for the OpenAPI Specification?

The Arazzo Specification and Overlays (both with a 1.0 version hot off the presses) look really promising, although I haven’t had much of a chance to dive into them yet. The ideas behind Arazzo are really interesting, as up until now each API is defined in a description wholly separate from every other API, whereas Arazzo workflows will tie them together and show how multiple APIs are related to each other. This will really help future low-code applications that drive their API calls directly from OpenAPI descriptions. The more sophisticated we can get with describing the full flow of an application, the more automatic code generation we can do, which is great for programmer productivity.

Should more people get involved in developing the OpenAPI Initiative specifications and why?

Absolutely! We need to hear from the community so we know what we should work on next. How are you using OpenAPI in your projects, and where would you like to use it more? We’d especially like to know what things you find difficult or confusing, or perhaps types of APIs that you find difficult to express right now.
We do hear from users from time to time that are frustrated that their favourite software suites or IDEs aren’t fully OpenAPI 3.1-compliant, so if tooling vendors have any roadblocks here, we really want to know, so we can help.

Additionally, we love hearing about new tools that do things we didn’t expect, and what other things we could be capturing in OpenAPI descriptions that we haven’t thought about yet. Let us know what you’re doing and we’ll showcase you on our Tooling page! (https://openapi.tools)

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