Skip to main content
search
Category

Blog

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!

Sep 17
Love1

OpenAPI Community Heroes – Lorna Mitchell

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 latest Community Hero who makes a huge contribution to OpenAPI is Lorna Mitchell. Lorna is VP of Developer Experience at Redocly and a member of the Technical Steering Committee for the OpenAPI Specification. Lorna is a software engineer, published O’Reilly author, open source maintainer and general API enthusiast, who describes herself as “getting stuck on an OpenAPI question one day, and never left!”

Lorna gave us her thoughts on all things OpenAPI and Arazzo.

What drives your interest and involvement in the OpenAPI Specification?

My whole career has been around getting computers to talk nicely to one another! I’ve built APIs, taught APIs, written books on these subjects, advocated for APIs, now I work on API developer tools. APIs are important, interesting, and mostly under-celebrated.

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

That’s a hard question! I’ve made very tangible additions such as designing the webhooks support for 3.1, but I think being a regular at the TDC meetings and in the GitHub projects, enabling other people to be heard and have their contributions accepted has been really important. Now I’m a technical steering committee member myself, which is pretty significant!

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

It all looks promising.

How will the Arazzo Specification benefit the development of the OpenAPI Specification?

Arazzo gives us a way to connect API calls in sequence, and it’s a good reflection of how APIs are actually built and used today. Building on the foundation of OpenAPI is brilliant for the ecosystem and we’ve needed something like Arazzo for quite a while.

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

As the project matures, we’re seeing more of an ecosystem around OpenAPI. Within the project itself, we’ve got Arazzo, Overlays, and more examples and learning resources. In the wider industry, lots of exciting new tools are springing up and people are starting to skill up more on what they can do with OpenAPI.

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

Seeing AsyncAPI release a new major version last year was exciting, there are lots of interesting use cases in that space. I’m also really interested in how we manage these large API landscapes so APIs.json is one to watch.

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

Yes please! More help is always welcome, but what I’d really like is to hear more voices. More questions in the GitHub discussions, more comments from more different people on the proposed changes. End users, tools makers – everyone should have their say, and I hope they will join in!

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.

Jul 25
Love1

OpenAPI Community Heroes – Frank Kilcommins

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.

We are delighted to share our next Community Hero, Frank Kilcommins. Frank has over 15 years of experience in the technology industry, with his roles spanning from software engineering to enterprise architecture. His mission is to inspire, engage with, and support the API community and SmartBear customers across the end-to-end API Development Lifecycle and Management space.

Before joining SmartBear, his most recent roles focused on API-led Digital Transformations and architecture modernization within multinational enterprises. In addition to his roles at SmartBear, Frank is a member of the OpenAPI Initiative Business Governance Board and has spearheaded the new Arazzo Specification for API workflows.

What drives your interest and involvement in the OpenAPI Specification?

APIs are critical to the digital world around us, and it’s an area of tech that I’ve been heavily working on for the last decade. I’m naturally drawn to the resilience and affordances brought by specifications and standards and as a result, I’ve been championing OpenAPI adoption and usage within various jobs engaged with HTTP-based APIs. My initial engagements with the community and OpenAPI Initiative were from a learning perspective (and still are) but over time I’ve been able to support others and contribute back as well.

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

I would have to say championing the Workflows Special Interest group and driving the creation of the Arazzo Specification have been my personal highlights.

My contributions on the core spec have been mostly verbal or via the Slack workspace apart from revamping the https://spec.openapis.org site to be multi-spec ready. Within the broader OpenAPI Initiative, I’ve also looked to improve some of the related artifacts and repositories. This includes things like ‘community’ to streamline the information on Special Interest Groups and participation, ‘OpenAPI-Style-Guide’ to have a dedicated barbell logo and usage instructions (yes, it matters 😉), and in a very small way the OAICourses material.

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

The structural changes are going to significantly reduce the verbosity of OpenAPI descriptions which is great for humans and machines dealing with large API surface areas. Additionally, the hardening of external referencing and improved multi-document support will make our lives as tooling builders much better, and in turn the developer experience for end-users.

How will the Arazzo Specification benefit the development of the OpenAPI Specification?

Arazzo addresses a very natural problem in aiding the description of deterministic use-case-orientated sequences of calls to APIs, be they in a single OpenAPI description, or spanning multiple. In general, thinking and building software in terms of use cases is what comes naturally to humans, so we predict that Arazzo will help improve the state of API design and design thinking. This niche focus can benefit OpenAPI by reducing the burden of supporting such capabilities both from a core spec perspective as well as that of authors who are currently challenged with trying to embed such associations within markdown or extensions.

Moving forward there is scope/vision for the sharing of components between OpenAPI and Arazzo which will bring another set of benefits to the community.

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

I’m excited by the launch of the Arazzo Specification, and the maturing of the OAI into a multi-specification project under the Linux Foundation. This combined with continued work of the Special Interest Groups will help to drive a more rounded OpenAPI Specification by addressing the needs of the community across industry verticals and specialist topics.

Personally, I would like to see a certification process for specification compliance (some of this being spearheaded by Henry Andrews with the OASComply project). Ensuring tool vendors advertise the compliance levels improves transparency for API practitioners and end-users. Ultimately, it can potential also help speed up the adoption of newer specification versions.

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

The elephant in most rooms right now is AI. It will be interesting to see how AI will consume standards, connect with standards-based APIs, and indeed help humans produce, understand, and consume APIs. The Arazzo Specification, as well as designs for OpenAPI 4, are specifically crafted with AI in mind. For example, Arazzo specifically has the semantic determinism to ensure that API sequence execution can be safely handed off to an AI agent.

The evolution of AsyncAPI into a v3 generation is also one to watch. Future collaboration between OAI and AsyncAPI is natural as in many practical situations those producing or consuming APIs are not limited to a single style.

In other areas, I’m particularly interested in developments within OAuth, the OpenID Foundation for OpenID Connect as well as FAPI. Keeping the financial theme, PSD3 also holds promise with respect to enforcing API standardization and performance. It’s also encouraging to see various governments, including the EU, form opinions on the importance of APIs and put forward opinions on API standards and specifications.

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

Absolutely! As I mentioned at the outset APIs are the critical tissue that enables much of the technology around us. If you have an interest or passion in APIs, then the OAI is a community that welcomes participation. Just like any open-source project, involvement and participation comes in many forms and caters for a diverse range of skills.

Jul 19
Love1

A Buy-now, Pay-later Use Case for Arazzo

By Blog

Buy-now, Pay-later – An Example Use Case for the Arazzo Specification

The continued growth of the API economy presents us with an ever-increasing number of APIs we use in building systems and doing business. With this volume of APIs comes complexity. We find ourselves calling multiple APIs, from the same provider and across multiple API providers, to execute a given business function. This growth in the interdependency of API operations has created a need for sequences of API calls to be described programmatically , which is why our 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.

The use case for an Arazzo description can be applied across almost any industry or vertical. Financial services APIs, for example, demonstrate how such orchestration needs have grown across an ecosystem, where examples of APIs that need to be called in sequence are common for operations like account opening and payments. Buy-now, pay-later (BNPL) is one such use case, as this generally requires multiple API calls to secure a loan at the point of purchase. The sequence of steps can be generalized as follows:

  1. Product Eligibility Check: Customers select the BNPL option at checkout. An API call is made to correlate the items in the customer’s basket with BNPL finance options. The BNPL options are then displayed to the customer.
  2. Customer Selection: The customer chooses an offer from the list displayed. An API call is then made to retrieve terms and conditions.
  3. Eligibility Verification: Once the customer has selected the product and accepted the terms and conditions, an eligibility/credit check may be required, which may involve enrolling the customer on the BNPL platform.
  4. Initiate BNPL Transaction: With product selection and eligibility complete the BNPL transaction then takes place. An API call is made from the checkout provider to the BNPL platform with the order details and customer information.
  5. Authentication & Authorization: The customer may then be required to authenticate themselves at the BNPL provider and authorize the transaction. This may happen through redirection to the BNPL platform.
  6. Finalize Payment Plan: Once the transaction is validated and the customer authenticated, the checkout will retrieve the finalized details of the loan including the payment schedule, interest rates, and so on.
  7. Order Confirmation: Confirmation of the BNPL transaction and payment plan acceptance is then signaled through an API call.
  8. Update Order Status: With financing secured the eCommerce platform will proceed with fulfillment and confirm fulfillment back to the BNPL platform.
  9. Payment Updates: Optionally, for subscription-based products, there may be ongoing updates over callbacks or webhooks from the BNPL platform to the eCommerce platform, with events such as missed payments or loan completion.

The sequence diagram below reflects the steps 1 to 8 described above:

This example reflects how composable software services have become and how we can tailor our platforms based on the myriad of available API providers. The steps and sequence diagram show the complexity that typifies such business flows, especially in eCommerce and is exactly the scenario Arazzo looks to address. An Arazzo description is designed to help platform providers describe flows across their APIs and take the guesswork out of stitching them together. This is of significant benefit for API consumers as they get a structured, versioned description of the required steps that they can use to implement their integration. This gives API consumers a reference point they can rely on to ensure their workflow is implemented as expected and working correctly.

To help bring this example to life, we’ve created a BNPL Arazzo description and OpenAPI description in the Arazzo Specification repository.

The BNPL description includes the inputs to the sequence described above, defined as a Workflow Object:

- workflowId: ApplyForLoanAtCheckout
  summary: Apply for a loan at checkout using a BNPL platform
  description: Describes the steps to secure a loan at checkout from a BNPL platform. It is a multistep process that requires multiple API calls across several API providers to be completed successfully.
  inputs:
    type: object
    required:
      - customer
      - products
    properties:
      customer:
        # Customer properties
      products:
        # Product properties

The Workflow Object defines the parameters required to initiate the flow which, in this case, include the parameters to make the first API call to check product eligibility and a later step to check customer eligibility for the loan. The inputs to this workflow are:

  • The customer details, which can be the full details or a URL that indicates an existing customer resource if the customer is already enrolled on the BNPL platform.
  • An array of products, used to assess the customer basket qualification for a checkout loan at the BNPL platform.

All other arguments in the sequence are then elicited using response properties from each API call. These are represented by Step Objects that define the sequence, the conditions that indicate a step has been successful and pointers to dynamic values that can be passed between steps.

For example, the first step in our BNPL use case was to check products in the customer’s basket that were eligible for a loan. This is encapsulated in the following Step Object:

- stepId: checkLoanCanBeProvided
  description: |
    Call the BNPL API to filter the basket for products qualifying for checkout loans. Pass in the array of products from the workflow input as the payload for the API call.

    Act on the response payload:

    - If a list of qualifying products is returned then submit customer choices.
    - If the list of qualifying products is empty then end the workflow
  operationId: findEligibleProducts
  requestBody:
    contentType: application/json
    payload: |
      {
        "customer": "{$inputs.customer}",
        "products": "{$inputs.products}"
      }
  successCriteria:
    - condition: $statusCode == 200
  onSuccess:
    - name: existingCustomerNotEligible
      type: end
      criteria:
        - condition: $statusCode == 200
        - condition: $response.body.existingCustomerNotEligible == false
    - name: qualifyingProductsFound
      type: goto
      stepId: getCustomerTermsAndConditions
      criteria:
        - condition: $statusCode == 200
        - context: $response.body
          type: jsonpath
          condition: $[?count(@.products) > 0]
    - name: qualifyingProductsNotFound
      type: end
      criteria:
        - condition: $statusCode == 200
        - context: $response.body
          type: jsonpath
          condition: $[?count(@.products) == 0]
  outputs:
    eligibilityCheckRequired: $response.body.eligibilityCheckRequired
    eligibleProducts: $response.body.products
    totalLoanAmount: $response.body.totalAmount

The Step object definition provides:

  • The unique identifier for the definition.
  • A reference to the operationId value of the associated Operation in the target OpenAPI description.
  • A Request Body Object to describe the inputs to the step, which can include external inputs defined in the Workflow object. In this case, we reference the products in the customer’s basket and their customer details.
  • The success criteria that define whether the step was successful. This is expressed through one or more conditions evaluated using HTTP return codes and properties of the response body, referenced using JSON Path.
  • Directives on what to do if the API call was successful. In this case, if zero qualifying products are returned the workflow ends.
  • Outputs from the step that allows dynamic values to be passed to subsequent steps. In our example, these include the filtered product details that can be shown to the customer to indicate which products are eligible for a BNPL loan and whether a customer eligibility check is required.

The Arazzo Specification is therefore geared towards providing a simple, declarative approach to describe a sequence of API calls to provide flexibility for the API provider and ease of use for the API consumer. You can follow our full example using the links above to discover more about how the Arazzo Specification can help you describe complex, multistep sequences of API calls.

If you are interested in learning more about Arazzo please read the specification, visit our discussions or join us on Slack. Feedback on the Arazzo Specification is most welcome!

Jun 07
Love0

OpenAPI Initiative Newsletter – June 2024

By Blog

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

Initiative News

We are excited to announce version 1.0.0 of the Arazzo Specification! Arazzo is the new official name for the Workflows Specification, which was decided on by the community after many rounds of debate. Arazzo is a specification that allows API providers to describe sequences of API calls, both within one API or across various APIs, with the means to link them together so implementers can orchestrate a series of steps based on known success and failure criteria. Arazzo is a significant step forward in describing the increasingly complex API landscape. You can learn more about Arazzo in our announcement.


The announcement of the Arazzo Specification means that the OpenAPI Initiative is moving to a multi-specification organization, with the OpenAPI Specification and the Arazzo Specification both falling under the OpenAPI Initiative umbrella. This will change how we maintain specifications consistently, especially as we add more specifications in the future. We will discuss this in a future post that describes our evolving landscape and governance approach in more detail.


In case you’re wondering: Arazzo means “Tapestry” in Italian, and was chosen because the specification is both about intricately weaving together something out of smaller things, and about telling a story that ends up being bigger than the sum of its parts.

Specification News

With planned patch releases for the 3.0 and 3.1 branches coming up, it’s “clarification season” in the OpenAPI Specification project. These changes address common questions and confusion, to make sure that the specification is as clear as possible. We’ve also made improvements to the tooling for publishing the specifications as HTML from the Markdown sources that we maintain in the repository, in preparation for releasing new versions. You can see all the changes and activity on the OpenAPI-Specification repository on GitHub.

Our biggest contributor for clarifications to the OpenAPI Specification and fixing an enormous number of ambiguities and open questions in the specification is Henry Andrews. A big thank you to Henry for all his effort in making our “small print” readable by anyone.

Our weekly Technical Developer Community meetings (0900 Pacific time on Thursdays, everyone welcome) are well-attended, full of thoughtful debate and discussion, and the engagement there – as well as all the hard work in between the meetings – continues to move us forward with purpose.

Community News

In this newsletter, we announce our Community Heroes feature, which provides a profile of an invaluable member of the OpenAPI community. In this first feature, we interviewed Henry Andrews, a subject matter expert in OpenAPI and JSON Schema and a prolific contributor to the community. You can read more on our blog.

We can also bring you news of the imminent release of our first OpenAPI Initiative training course, OpenAPI Fundamentals. This course provides foundational knowledge of OpenAPI, with the history of the language and practical examples of creating and using an OpenAPI description. This free course is available on The Linux Foundation Training and Certification platform from June 11th 2024.

Events Round-up

The summer is fast approaching in the Northern Hemisphere and consequently, the conference schedule tends to take a hiatus. We have, however, been busy running our OAI track at various conferences since our last newsletter. The OAI track aims to bring together community leaders and practitioners to provide a focused and detailed series of talks on subjects across the spectrum of OpenAPI Initiative specifications. The tracks are orchestrated by Erik Wilde, who describes them as:


“The OAI Track brings the API community together around OpenAPI and standardization in general. We typically have presentations about core specification topics, we talk about practices and tooling, and we also have contributions where presenters share how OpenAPI and standardization helped them on their API journey. Join us at any OAI Track to get the latest news and high-quality presentations about OpenAPI and other OAI activities!”


The OAI track was hosted at three apidays conferences in April and May, in Singapore, New York, and Helsinki, as well as at the JAX Conference in Mainz, Germany, in April. We heard from great speakers, including Frank Kilcommins who covered the finer points of Arazzo (including unveiling the name at apidays Helsinki). Darrel Miller looked at consuming APIs for “SDK Haters” in New York, while Sohaib Tariq discussed lessons learned from one million API definitions in Singapore.


We will be running the OAI track at conferences in the future, including the apidays Paris conference, where we plan to provide extensive training sessions on OpenAPI. We will launch an official “OAI certification program” in the second half of the year, at both the on-site training sessions at the apidays Paris conference and online courses. Stay tuned for details and please check out the OAI event calendar for a full list of upcoming events.


We also want to hear from you! Please get in touch on the Outreach channel on Slack with news of upcoming events, meet-ups, or anything you want to share with the OpenAPI community. We’d also love to hear about your experiences of using OpenAPI in designing and implementing your APIs, and share those experiences with the community on our blog.

Finally…

That’s it for this newsletter. If you have 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.

May 29
Love0

Meeting Orchestration Needs with Arazzo

By Announcement, Blog

Today we are delighted to announce the release of Arazzo, a new OpenAPI Initiative specification designed to describe sequences of API calls to meet the orchestration needs of API providers and consumers.

In a digital economy increasingly powered by APIs there is a need to accurately reflect the increasing complexity of the integration required to do business. Organizations calling multiple APIs to execute business flows and functions, sometimes across multiple service providers, require guidance and support to correctly implement sequences of API calls, with cognizance of success and failure at each step.

The Workflows Special Interest Group (SIG), part of the OpenAPI Initiative umbrella of specifications, has created the first release of the Arazzo Specification to meet the increasingly complex integration needs. Arazzo will allow API and integration service providers to build on top of OpenAPI Specification, providing information on sequences of API calls that comprise a flow or function.

Using Arazzo API providers can:

  • Link multiple operations, described through OpenAPI or other Arazzo descriptions, into one sequence of activities.
  • Provide criteria that describe success or failure based on the responses received from the APIs that API consumers call.
  • Implement variables that can carry dynamic variables from one API call to another, ensuring that data is successfully carried, as needed, through the context of the described sequence.

Like the OpenAPI Specification, the goal is to create a rich description language that can be used both for documentation and to automatically create integration code from machine-readable sources.

Frank Kilcommins, Principal API Evangelist at SmartBear and member of the Workflow SIG team, describes Arazzo as:

“An important milestone on the path to improved API maturity across the industry. By providing deterministic recipes for value-based usage of APIs, the Arazzo Specification, through its human- and machine-readable attributes, acts as living API documentation, reducing dependence on out-of-band onboarding guides. It ensures assertable qualities for API providers and regulatory stakeholders across the API lifecycle, while also empowering tooling vendors to craft the next wave of SDKs and code generators.

The Arazzo Specification enables human API consumers to better understand how to use and combine APIs, focusing on their jobs to be done, thus reducing their mean time to integration. Concurrently, it offers a consistent and interoperable mechanism for the new wave of AI consumers to achieve expected API outcomes first and every time.”

Arazzo will evolve as more organizations and tooling makers implement the specification. Please visit the specification page and repository, or join our Slack channel for more information.

Close Menu