Skip to main content
search
All Posts By

OpenAPI Initiative

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

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!

Aug 27
Love1

OpenAPI Initiative Newsletter – August 2024

By Blog

Welcome to the OpenAPI Initiative August 2024 Newsletter, our regular round-up of the latest stories from across the OpenAPI landscape. It’s vacation season in the northern hemisphere, but there is plenty of news to share!

Initiative News

Our Arazzo Specification was announced in our last newsletter which, in case you missed it, is a description language that allows API providers to describe sequences of API calls, both within one API or across various APIs. The arrival of Arazzo has created a significant buzz in the community, with a great deal of interest in how Arazzo can meet many use cases.

To help introduce Arazzo we’ve started another initiative, our OpenAPI Hangouts series! We held our first OpenAPI Hangout on 30th July 2024, where Budha Bhattacharya, Frank Kilcommins, Lorna Mitchell, and Erik Wilde discussed Arazzo in detail. If you missed the Hangout, please watch the video on the event page. Keep an eye open for future OpenAPI Hangouts by following us on LinkedIn.

We also took a detailed look at Arazzo through a real use case, namely for API consumers implementing a buy-now, pay-later (BNPL) solution in their e-commerce solution. While the BNPL API and platform in our use case are examples they accurately represent the complexity of such e-commerce orchestration and workflow requirements. You can discover more about the full BNPL example on our blog.

Specification News

Our Specification website has recently undergone a revamp. All versions of the OpenAPI Specification are now provided through this page, together with v1.0.0 of Arazzo. We hope these changes will provide a focused, “one-stop” solution for readers of our Specifications.

Work continues on multiple releases of the OpenAPI Specification. We now have several releases in-flight, with 3.0.4, 3.1.1, 3.2, and 4.0 coming down the tracks.

3.0.4 and 3.1.1 are patch releases that make OAS 3.0 and 3.1 much clearer without adding any new requirements. We’ve expanded and improved explanations of parameter serialization, discriminators, reference resolution, and more. We’ve also updated our citations of security standards and improved the consistency and clarity of our wording throughout the specification.

3.2.0 will be an incremental step towards “Moonwalk” that will be strictly compatible with 3.1. Our goal is to introduce a few Moonwalk improvements along with other small fixes that will be easy for tooling providers to implement in the near future. This will help bridge the gap to the eventual release of 4.0.

Work on OpenAPI 4.0, codenamed Moonwalk, also continues apace under the auspices of the Moonwalk Special Interest Group (SIG). You can catch up with latest developments on Moonwalk Discussions, where we publish discussion points from each meeting.

Our specification meetings are, of course, open to anyone. If you want to join to listen in or contribute, you’ll find the meetings in the OAI calendar.

Community News

We recently announced our Community Heroes feature, which profiles an invaluable member of the OpenAPI community. Our second Community Hero is Frank Kilcommins, Principal API Technical Evangelist at SmartBear, who has been instrumental in creating the Arazzo Specification.

Please read more about Frank on our blog. Also let us know if you have any suggestions for a future Community Hero and we’ll do our best to feature them!

Events Round-up

Conference season is also about to ramp up again and we’ve got several OAI tracks and sessions in the pipeline.

Apidays London – 18th – 19th September, 2024

Our next event will be apidays London, where Erik Wilde will host our OAI track. The theme of apidays London is “APIs for Smarter Platforms and Business Processes”, and will focus on how AI and APIs act as enablers for businesses. Our OAI track will therefore look at standards and practices in the OpenAPI ecosystem that act as enablers for business. We’ll hear from Frank Kilcommins with an update on Arazzo, Lorna Mitchell on API governance, and Gobe Hobona on API standardization for geospatial ecosystems.

Nordic APIs Platform Summit – 7th – 9th October, 2024

The Nordic APIs Platform Summit is held in Stockholm in October each year and offers a wealth of experiences and perspectives across the API economy. OAI is offering an OpenAPI Fundamentals workshop at the Summit, with the content based on our Linux Foundation course. The workshop will be led by Budha Bhattacharya and Chris Wood, and will be an “ask me anything” format to provide you with deep insights on your target topics. Please follow the link to register.

Event Outlook

We are planning OAI tracks at the following events:

Finally…

That’s it for this newsletter. If you are in the northern hemisphere we hope you are having a great summer!

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.

Nov 06
Love0

Apidays Paris 2023 – with an OpenAPI Track – is Coming This December!

By Announcement, Blog, Events

The OpenAPI Specification is an integral part of software development and delivery of APIs. In 2023, we have been joining multiple API related conferences to connect directly with API users and enthusiasts around the world. Next up, the City of Light! Join us for the OpenAPI Initiative’s “OAI Track” at apidays Paris on December 6-7, 2023!

See our apidays Paris events page here.

What is the OAI Track?

The OAI Track is a specialized forum at apidays Paris hosted by the OpenAPI Initiative (OAI). This focused track aims to provide a platform for API practitioners to share and exchange valuable insights, experiences, and best practices related to OpenAPI. At Paris, we will have 3 different sessions with a total of 12 speakers! 

OAI Track Program Sessions

  • Current and Future Trends in API Specifications
  • Improving APIs and API Landscapes with API Descriptions
  • API Governance and Management with API Descriptions

Call for Contributions

The OAI Track is currently inviting contributions from interested individuals and organizations. If you have an experience or insight to share, we would be thrilled to include your voice in the discourse.

👉 Submit Your Proposal Here: https://apidays.typeform.com/to/ILJeAaV8?typeform-source=www.apidays.global#event_name=xxxxx 

👉 Register here: https://ticket.apidays.global/event/apidays-paris-2023/8a1f3904-e2be-4c69-a880-37d2ddf1027d/cart   

Why Should You Participate? 

  • Knowledge Sharing: Learn from industry experts and peers actively involved in API management and OpenAPI specifications.
  • Networking: Connect with a passionate community of API developers, architects, and business stakeholders.
  • Visibility: An opportunity to present your work and insights to a highly specialized and relevant audience.

Join Us, Join the Conversation!

Whether you’re an adept API craftsperson or an enterprise visionary keen on tapping into API magic, the OAI Track provides a fantastic platform to immerse and interact with the best of the API world.

Date: December 6-8, 2023

Venue: CNIT la Défense, Paris, France

Don’t miss out on this unique opportunity. Mark your calendars, and prepare to dive deep into the world of OpenAPI.

We hope to see you there!


For further updates and announcements, watch our apidays Paris page.

Sep 07
Love0

Join Us at apidays Australia 2023 for a Full-Day OAI Track

By Blog, Events

The OpenAPI Specification is an integral part of development and delivery of APIs. In 2023, we are joining multiple API related conferences to connect directly with API users and enthusiasts around the world. Join us for the OpenAPI Initiative’s “OAI Track” at apidays Australia in Melbourne on October 11th and 12th, 2023!

What is the OAI Track?

The OAI Track is a specialized forum hosted by the OpenAPI Initiative (OAI) as part of the larger apidays Australia conference. This focused track aims to provide a platform for API practitioners to share and exchange valuable insights, experiences, and best practices related to OpenAPI.

Key Focus Areas

  • User Stories: How are you or your organization using OpenAPI?
  • Tooling: Showcase tools you use or develop to enhance OpenAPI utilization.
  • Specification Extensions: Share any augmentations or adaptations you’ve made to the OpenAPI Specification that could benefit the wider API community.

Call for Contributions

The OAI Track is currently inviting contributions from interested individuals and organizations. If you have an experience or insight to share, we would be thrilled to include your voice in the discourse.

👉 Submit Your Proposal Here: https://apidays.typeform.com/to/ILJeAaV8?typeform-source=www.apidays.global#event_name=xxxxx

Why Should You Participate?

  • Knowledge Sharing: Learn from industry experts and peers actively involved in API management and OpenAPI specifications.
  • Networking: Connect with a passionate community of API developers, architects, and business stakeholders.
  • Visibility: An opportunity to present your work and insights to a highly specialized and relevant audience.

Get Inspired: Hear from apidays Founder

Still wondering if the OAI Track is the right place for you? Listen to Mehdi Medjaoui, the founder of apidays, discuss the essence and vision of the OAI Tracks at apidays events with Erik Wilde.

Join the Community!

apidays Australia is not just another tech event; it’s a rich learning ground and a launchpad for ideas to advance the API ecosystem. Whether you’re a seasoned API developer or a business leader looking to harness the power of APIs, the OAI Track offers an unparalleled opportunity to engage with the API community.

Save the Dates: October 11th and 12th, 2023

Location: Pullman Melbourne Albert Park, Melbourne, Australia

You can register here: https://ticket.apidays.global/event/apidays-australia-2023/f2d35972-9e81-401d-a29a-285fa1d00974/cart 

Don’t miss out on this unique opportunity. Submit your proposals here​​, mark your calendars, and prepare to dive deep into the world of OpenAPI.

We hope to see you there!
For further updates and announcements, watch our apidays Australia page.

Aug 31
Love0

Case Study: Using the OpenAPI Specification for Integrating SaaS Applications and Scaling Up to Hundreds of API Providers

By Blog

Guest blog post by Donald Atha, Software Architect, BetterCloud

One of the biggest challenges facing IT teams today is the increase in tedious and repetitive tasks driven by the explosive growth in SaaS applications over the last 10 years. Companies are using more and more SaaS products, which presents challenges when it comes to managing employee onboarding and offboarding, managing licenses and permissions, and resolving help desk tickets. At BetterCloud, we give IT teams the tools to reduce the amount of manual work on their plate with automations and configurable workflows. As the number of SaaS applications grows, our customers rely on our library of SaaS integrations to also grow.

Testing OpenAPI Generators for Rapid Integration

Recently the Innovation Team within BetterCloud, a team tasked with discovering and testing new capabilities that accelerate innovations, took on the challenge of prototyping a solution that would allow us to more rapidly integrate with various SaaS applications and scale that solution to onboard hundreds of API providers. The team agreed early on in order to reach the ambitions of the business, we would need to automate much of the process. The team also agreed that this would be possible because much of adding a new integration is the same and that the OpenAPI Specification would allow us to automate pieces of this by using existing community generators. 

To fully understand the problem, it helps to understand what it means to add an integration at Bettercloud and a bit about our product. BetterCloud’s workflow engine automates processes like employee onboarding by detecting when a new employee is hired and subsequently granting access to the various SaaS applications required for their role. This onboarding scenario is just one of many use cases we support. All these use cases invariably necessitate ingesting and storing data from the 3rd party provider and updating the provider’s state. For instance, in the onboarding use case, the ingestion process fetches employee data, detects a change in status, and triggers the onboarding workflow. This workflow calls the provider’s APIs to create accounts or grant access to shared resources for the employee—functionality we internally refer to as “actions.”

When embarking on adding a new integration, BetterCloud begins by validating that the provider has the necessary APIs to support our use cases. This crucial step sets the stage for efficiently accessing required data and assessing whether the provider’s APIs are compatible with our action use cases. The OpenAPI Specification provides a consolidated view of this information.

Reducing the Amount of Code Written by Using the OpenAPI Specification

Once the API is understood, the next phase is implementing the ingestion logic. This phase involves calling the provider’s APIs to fetch and store all necessary data within BetterCloud’s infrastructure. The team has explored two methods to coordinate this, both leveraging the OpenAPI Specification. The intent with both approaches is to reduce the amount of code that a developer must write when adding a new integration. The first involves code-generating an HTTP client in Java using the OpenAPI Java code generator, while the other approach uses extensions to markup the spec, enabling the configuration of the ingestion logic. This marked-up spec feeds into a general-purpose engine that implements the logic based on the extensions. This covers the ingestion of data from the APIs, but once acquired, it must be stored to serve our applications. 

BetterCloud utilizes a SQL database to store the entities we ingest. To create the schemas, the team employs the OpenAPI MySQL generator, Flyway, and Terraform. These tools facilitate the creation and configuration of a database for the new provider. The team was able to slightly modify the existing mustache templates of the MySQL generator in order to add our internal fields such as customer id. Since both the ingestion data models and the MySQL data schemas derive from the OpenAPI Specification’s entities, automation of this process becomes straightforward as the data models are aligned. With just an OpenAPI definition, we can generate a new database and its schemas at the click of a button in all of our environments!

Conclusion – Better Scaling the OpenAPI Specification, Better Value

We anticipate that this approach will allow us to bootstrap the ingestion portion of adding a new integration. By automating and code-genning common elements, the team can concentrate on the unique aspects of each new integration. Much like how we at BetterCloud automate workflows for IT teams to allow them to scale the impact of their work, the OpenAPI Specification has given us the tools to build our own automations that scale the value we can provide to our customers.

Close Menu