From APIDays Paris: OpenAPI 3.1 Coming Soon

By Blog

Originally posted in the LORNAJANE Blog – Thank you, Lorna!

What’s New in OpenAPI 3.1

With OpenAPI 3.1 coming “soon”, I gave a talk at APIDays Paris about what to expect. But I’m a great fan of the written word as reference so here’s a written recap of what’s in the next OpenAPI release.

Top features:
– Compatible with JSON Schema 2020-12
– Webhook support
– Many other minor improvements

Version Numbering

As of OpenAPI 3.1, the OpenAPI project doesn’t follow semantic versioning. That sounds like a totally irresponsible decision but it actually makes some sense for a standard where every API description clearly states the version of OpenAPI it relates to. Also, they don’t let me make the rules, sadly! It’s not a major release, but some things had to be undone and redone to accommodate JSON Schema.

JSON Schema 2020-12

This is really big news, so much of OpenAPI is used alongside JSON Schema and the 3.0 release was quite a long time ago and didn’t quite accommodate everything that makes sense today in JSON Schema. This post won’t cover what’s new in JSON Schema itself but I’ll try to round up the main points from the perspective of OpenAPI users.

First of all: types can now be arrays of types, so something could be of type [string,number]. The available types also include null, so more common will be [string, ‘null’]. This does impact on existing OpenAPI documents as from 3.1, the nullable keyword is removed – use the array of types and one of the types is null.

  - name: friendly-label
    in: query
        - string
        - 'null'

OpenAPI 3.1 is getting support for the examples keyword within a schema, allowing an array of examples. Often the array only contains one element though. The original singular example keyword is still valid, but examples is recommended and if both are present then examples is preferred. Be aware that this array of values is in contrast with the other use of examples in OpenAPI, in a MediaType content object, where the examples field is a map with string keys. Confused? So are we. There is a post all about OpenAPI examples from Phil that explains it all!

A couple of other things are coming in from JSON Schema into the OpenAPI schemas. First of all: arbitrary keys are allowed in a schema; OpenAPI has relaxed its constraints on which fields can appear where to accommodate JSON Schema format objects. Also it’s possible to $ref to an object, then put keys alongside it which are considered in addition to what is defined in the component.

      $ref: '#/components/schemas/style'
        - hue

None of these changes are huge, but having the ability to use JSON Schema within OpenAPI is brilliant for anyone wanting to use the two together so to have this commitment to supporting the ever-improving JSON Schema is excellent news.


I’m totally biased because I proposed this feature. I couldn’t believe that OpenAPI didn’t already support this common use case and it took time to realise that it wasn’t that I didn’t understand how to do something – that thing really was outside what OpenAPI 3.0 expected APIs to describe.

OpenAPI 3.0 does have support for callbacks so if the user should make an API call, supply a URL, and stand by for incoming HTTP requests to that URL as a result, that’s already supported. This is ideal when an endpoint asynchronously returns data, or for some situations where an API call “subscribes” to an event and gives a URL to send things to.

OpenAPI 3.1 goes a step further and allows webhooks which are incoming HTTP requests that are in response to some external event or stimulus. A great example would be if you’ve ever linked anything to a GitHub push event, or an incoming order/payment/message (and I’ve been working for a communications company for a few years, so you can immediately understand how I got entangled in this). The webhooks are described a LOT like the existing callbacks are, and indeed both are much like the existing request descriptions, so I hope this change will be easily adopted by everyone who has a two-way API like this.

The new webhooks keyword is a top-level element, alongside paths. There are also changes to the required fields: OpenAPI 3.0 required openapi and info and paths but in OpenAPI 3.1 only openapi and info are always required, but the document must also contain at least one of paths or webhooks or components. This is brilliant because it allows API descriptions to contain only outgoing API calls, only incoming webhooks, only components that might be referred to by other documents, or any combination or all of these – and still be valid in its own right.

Anyway, back to the webhooks.

      operationId: inbound-sms
          application/json: ...
      responses: ...

Within the webhooks section, each incoming “thing” has a key (such as inbound-sms in the example above) and then it goes on just … looking like a pathItem, because that is all it is. You don’t need to specify the URL path that the webhook will come in on (often the user can nominate that anyway), just explain what will arrive and you are done. Oh and related to this: pathItem is now allowed in the components section and you can $ref to a pathItem from either a path or a callback or a webhook.

Fancy a sneak preview of what the webhooks will look like when the tools get support for it? Redoc already has preview support if you use x-webhooks in your 3.0 OpenAPI documents! I mean, it just looks like really competent API documentation but that’s what we need here 🙂

A note about webhooks and callbacks. Quite a few endpoints could be considered as either a webhook or a callback, and I have already started getting questions about which to use. It probably doesn’t matter but if there is no preceeding API call that the callback is a response to, then it’s definitely a webhook. Where there is some previous API call with a URL, then it’s probably up to you how you want it to work. For example at Vonage the configuration for where to send events for an incoming Message is at the application level, do you do that with the Application API – but I’d rather have the API description with the incoming Message webhook detail shown next to the send Message API call, in the same document, tagged and grouped together in the Message API description. The webhooks keyword gives you the flexbility to approach this as you will.

Small But Perfectly-Formed Upgrades

There are so many small things that have been added in OpenAPI 3.1 but I’m picking my favourites to include! As with every *.1 release, there are things that seemed like a good idea for the *.0 release that can now be tidied up a little now we’ve all tried them out in anger, it’s a good thin.

I’ll start with the one I want to implement immediately (or as soon as the tools allow): $ref can now have summary and description as siblings, and they override any existing fields on the referred-to component.

        - $ref: '#/components/parameters/item'
          description: The specific item in question

There are a few minor things in the info section as well:

  • Inside info, you can now have summary alongside the description field. Both are optional – title is still required.
  • In the license object you can use an SPDX code in the new identifier field instead of a url alongside the required name field if you prefer

Finally, paths are no longer required to have responses field for every endpoint. This is useful when an OpenAPI document is under construction because it means that it will validate even when you’re still only sketching out the endpoints that the API definition will include.

Further Reading

I’ll share links to my talk when the recording is published (the slides are on notist but keep up with the current status of the OpenAPI 3.1 release and read the (much better) changelogs on the project itself for more information

Band Protocol Becomes First Blockchain Firm To Join OpenAPI Initiative

By Announcement, Blog

Press Release from Band Protocol:

Bangkok – 14 Dec 2020: Sequoia-backed cross-chain data oracle Band Protocol, has joined the OpenAPI Initiative as the first blockchain firm alongside Google, eBay and Microsoft, to connect blockchain applications to common Application Programming Interfaces (API) and streamline the exchange of data between smart contracts and off-chain data sources. 

“Our mission is to define a common API standard for blockchain applications by collaborating with prestigious partners to bridge the gap between centralized data, APIs and smart contracts on the blockchain,” said Soravis Srinawakoon, CEO and Co-Founder of Band Protocol. 

An API is a software intermediary that makes it possible for two applications to share information easily and efficiently to enhance accessibility and user experience. 

By creating a common API standard, Band Protocol will allow blockchain applications to easily leverage off-chain APIs and data to better engage with centralized data sources and the wider technology community, enabling expansive use cases of smart contracts. 

This is an important step towards creating decentralized applications and smart contracts that are able to reliably and securely interact with traditional centralized technology and APIs and with each other. 

“The OpenAPI Initiative standardizes how the industry describes and documents APIs. We are thrilled to welcome Band Protocol as the first blockchain-based member to join the initiative,” said Marsh Gardiner, Marketing Group Chair at the OpenAPI Initiative and Product Manager at Google Cloud. 

The OpenAPI Initiative is a non profit foundation hosted at the Linux Foundation whose members include prominent organizations such as Google, IBM, Bloomberg, Microsoft, SAP and Oracle, among others. 

The initiative works to define common standard APIs to be used across different industries with Band Protocol becoming the first blockchain company to contribute to the initiative’s collaborative specifications. 

For more information on Band Protocol, please visit:

About Band Protocol

Band Protocol is a cross-chain data oracle platform that aggregates and connects real-world data and APIs to smart contracts. Backed by Sequoia Capital and the leading cryptocurrency exchange, Binance, Band Protocol enables smart contract applications such as DeFi, prediction markets, and games to be built on-chain without relying on the single point of failure of a centralized oracle. For more information, please visit: 

About 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. For more information, please visit: 

ASC 2020 Online – Don’t ASC, Still Learn

By Blog

The OpenAPI Initiative held its 2nd annual API Specifications Conference (ASC) online, September 9 – 10, 2020. A reimagined version of the famous APIStrat Conference, ASC continues to evolve and become a must-attend destination for folks interested in API specifications of all sorts. OpenAPI Specifications, RAML, Blueprint, gRPC, OData, JSON Schema, GraphQL, AsyncAPI, and other formats were all topics, enabling attendees to get familiar with these formats and discuss how to use them in practice.

ASC achieved a 91% attendance rate out of 373 unique registrations. We had 318 attendees, 42 speakers; 6 sponsors; and 7 staff. Feedback from attendees was overwhelmingly positive with 100% of survey respondents rating the overall experience as “Good”, “Great”, or “Excellent”. 88% said the content quality was “Great” or “Excellent.” Presentations included Github describing their journey towards adopting OpenAPI , OAuth2.1 and other updates in securing your API, and a unified API design methodology , among other engaging topics.

OpenAPI only charged $39 per person for the event and provided 18 community scholarships. We raised $2,500 for Code2040 and are proud to support their efforts.

While we missed seeing everyone in person, one benefit of an online event is that we could record all the sessions. We posted them on the OpenAPI Initiative Youtube channel. Also, many presenters uploaded their slide decks to Sched. We’ve made a brief tutorial to find sessions with slides easily. 

Stay tuned to learn more about ASC 2021 when information becomes available. Sign up for our Newsletter!

Implementer’s Draft (OAS 3.1 RC1) Available for Feedback – Please Respond by Nov 8!

By Blog

Request to the community! Please review RC1, implement it, and share with us your feedback by November 8th. The final version should come shortly after that.

Release candidate 1 (RC1) of OpenAPI Specification 3.1, the Implementer’s Draft, is available for testing and evaluation. 

The enhancements address some of the most requested features from the OpenAPI developer community. Specifically, the OpenAPI Specification is now fully compatible with the latest draft of JSON Schema. This has been a significant effort between the OpenAPI developer community and the members of the JSON Schema community. 

Changes include:

  • A new top-level element for describing Webhooks that are registered and managed out of band. Many thanks to Lorna Mitchell for driving this effort, using our new proposal process.
  • Improved support for identifying API licenses using the standard SPDX identifier.
  • The PathItems object is now optional to make it easier to create indexes of reusable components. Reusable PathItems can be described in the components object. There is also support for describing APIs secured using client certificates.

You can learn more about RC1 here.

Special thanks to Henry Andrews, Phil Sturgeon, and Ben Hutton for all their hard work and support.

OpenAPI Welcomes New Member Osaango

By Announcement, Blog

The OpenAPI Initiative, the consortium of forward-looking industry experts focused on creating, evolving, and promoting the OpenAPI Specification (OAS), a vendor-neutral, open description format for RESTful APIs, is announcing today that Osaango has joined as a new member.

Why did Osaango join the OpenAPI Initiative?

Marjukka Niinioja is the founding partner at Osaango, with over 10 years of experience with APIs. She and her team also organize apidays Helsinki and APIOps community. She explains: “We see OpenAPI specification as being both the problem and the solution. For many people, the design of API using the specification is just a technical task with the least effort put into it. For many more, the specification just doesn’t exist on their radar.” 

“Of course, there are also issues like tooling support that stop people from using it. Yet, we feel that the biggest issue is lack of knowledge, especially about the productization of APIs as well as API management. Both are interlinked and both benefit from using the specification,” she adds.

 “Skilled people + Good method = Great APIs”

Osaango has promoted open standards from its beginning. Marjukka Niinioja is the “mother” of APIOps Cycles method.  The method is the only openly licensed, Lean, and business-oriented method for developing APIs, and the full lifecycle. The method both promotes and depends on using API specifications to design, prototype, and document the API as part of the lifecycle. It promotes “APIOps,” the automated and transparent culture of building APIs. At its core APIops is like DevOps. The APIOps Cycles method extends APIOps. It includes also elements from product management, business design, and developer experience.

The method has been adopted in organizations around the world, from Finland to Argentina. As one user from Argentina put it: “We’re starting to build an API product, and discovering APIOps Cycles was fantastic because it helped us translate Lean Startup’s ideas into our world!” 

Together with partners and active community members, Osaango drives the open APIOps community with meetups and other activities to promote best practices. Osaango’s vision is to help make the API economy as known as a business model as the Software-as-a-Service, SaaS. But great APIs and great API Economy doesn’t happen by accident. For Osaango, API stands for “All People are Important,” not only application programming interface. API economy needs skilled people from all parts of the organization to collaborate. They need to understand the business benefits of having APIs. Not just any APIs but good, well-made standardized – truly Open APIs. This in turn requires design and development methods, and standards intended for APIs. This is how great APIs are built! 

Osaango is committed as an OpenAPI Initiative member to help lower the barriers of using the OpenAPI specification. Some of the first tasks for Osaango to take part in has been to:

  • Tackle the usability and accessibility of the OpenAPI documentation created by the initiative
  • Collect questions from the community about the various API specifications to be answered and documented to promote awareness and learning.

Learn more about the openly licensed method for API Development:

OpenAPI Resources

To learn more about how to participate in the evolution of the OpenAPI Specification:

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

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

OpenAPI is People!

By Blog

During the 2020 API Specifications Conference, influential members of the OpenAPI community gathered to discuss the people and processes that keep OpenAPI Initiative running smoothly. 

Collaboration between diverse companies is one of the most remarkable aspects of the OpenAPI community. Competitors realize the importance of creating a standardized description for APIs, and band together to accomplish a shared goal. In a recent discussion, influential community members celebrated OpenAPI’s accomplishments and reflected on its journey,

The talk featured: 

Mitchell discussed how implementing OpenAPI descriptions into her work has improved developer experience, helped internal development and allowed non-technical developers to better understand the content. She also provided insight into how developers can contribute to OpenAPI.

Any developer can join the Technical Developer Community, and participate in the community. This is a great place to ask questions, and share knowledge. On the other hand, the Technical Steering Committee (TSC) is composed of elected members that make high-level decisions to ensure OpenAPI operates smoothly. Gardiner and Miller are both part of the TSC, and discussed some of the difficulties associated with adding new features to OpenAPI.

The OpenAPI specification must meet the requirements of developers, but also be accessible to newcomers. Balancing functionality and complexity is a delicate act, and the TSC is often wary of adding unnecessary features. However, they listen to the community, and respond when there is rising interest in a particular subject.

For more information on how to contribute to the OpenAPI Initiative, visit the website!

From 0 to OpenAPI: How GitHub Described a 10 year old API

By Blog

GitHub recently adjusted their extensive, old API in order to comply with current OpenAPI standards. At the API Specifications Conference we got the opportunity to hear how they accomplished this feat from leaders on the project.

GitHub recently released an OpenAPI description for their REST API. It is now easier than ever to integrate projects with GitHub data using simple, standardized API calls. However, the API team at GitHub faced many challenges in describing their massive API so that it would comply with OpenAPI specifications. At one point, their API had over 37,000 errors and 500 invalid operators!

The enthralling explanation of their unique solutions to these challenges is available here.

A quick description of the OpenAPI Specification:

  • “The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.”

GitHub adopted OpenAPI specifications for their API in order to automate SDK’s and documentation. Using OpenAPI descriptions also helps ensure a consistent developer experience for users of the API. Finally, implementation of an OpenAPI description simplifies and standardizes the system, freeing up GitHub’s API team to work on other aspects of the project. 

GitHub Open Source REST API is available at the link below:

GitHub REST API Documentation:

Reasons to Register! ASC 2020 Keynote Panel Deep with Real-World API Experience

By Blog

APIs are essential in many scenarios today but are still just interfaces at the end of the day. So what gives an API meaning? How does an API remain usable and useful? Learn how to look past the interface for a deeper perspective on API products at OpenAPI’s ASC 2020.

The API Specifications Conference (ASC) is a place for API practitioners to come together and discuss the evolution of API technology. The ASC includes cutting edge technology keynotes and sessions that chart the future of APIs with in-depth specification and standards discussions. The event is designed to be highly interactive, with plenty of discussion time throughout the sessions.

Keynote Panel: What’s the Specification for API Products?

Moderated by Erik Wilde (Axway), join keynote speakers Mike Amundsen (, Inc.), Yina Arenas (Microsoft), Adam DuVander (EveryDeveloper), and Gail Frederick (Salesforce) on Thursday, Sept 10 at 9 AM PST as they discuss specification for API products. Learn how knowing why we are building these APIs should help us do a better job of identifying valuable specifications and delivering maximum value to customers.

Register Here

Keynote Moderator + Speakers

Erik Wilde supports companies on their digital journeys by helping them with their strategy and programs. Based on his background in computer science his focus is on technology. With his extensive experience when it comes to API initiatives within companies, however, he also focuses on business and organizational issues. Erik is a frequent speaker at conferences worldwide, publishes regularly in a variety of places, and is active in standardization efforts.

Adam DuVander is a developer communicator and cheerleader. He helps companies reach and engage with developers

through authentic content. Previously he worked for some of the best API and developer companies, including Zapier and SendGrid. Many still find his writing at ProgrammableWeb, where he served as the first editor of the influential journal. He’s a published author and international speaker, but his kids still aren’t impressed.

Yina Arenas leads engineering for Microsoft Graph, the gateway to data and intelligence in Microsoft 365 and one of the highest-profile engineering projects at Microsoft. During her career at Microsoft, she has been building the platform that enables developers to build applications that access data and relationships across Office and all Microsoft cloud services. She is from Bogota, Colombia and joined Microsoft in 2010 after graduating with a Master’s degree in Computer Engineering from the University of Virginia. She lives in Seattle with her husband and 4 energetic sons and actively participates in activities that grow, retain and empower women in technology. Find her on Twitter: @yina_arenas.

An internationally known author and speaker, Mike Amundsen consults with organizations around the world on network architecture, Web development, and the intersection of technology & society. He works with companies large and small to help them capitalize on the opportunities provided by APIs, Microservices, and Digital Transformation.

Amundsen has authored numerous books and papers. He contributed to the O’Reilly book, “Continuous API Management” (2018). His “RESTful Web Clients”, was published by O’Reilly in February 2017 and he co-authored “Microservice Architecture” (June 2016). His latest book — “Design and Build Great APIs” — for Pragmatic Publishing is scheduled for release in July 2020.

Gail Fredrick is the SVP Engineering, Salesforce Developer Experience at Salesforce.

Roles prior to Salesforce include VP Mobile and Developer Ecosystem at eBay,  engineering director at Intel’s Open Source Technology Center, the heart of Linux at Intel. Nerd-vana. And before that, mobile software architect at Medio Systems in Seattle, WA. Medio was acquired by Nokia/HERE in July 2014. Her treatise on standards-based mobile web development is “Beginning Smartphone Web Development”, published by Apress in December 2009.

OpenAPI Welcomes New Member APImetrics!

By Announcement, Blog


APImetrics provides an enterprise focused API monitoring solution that interfaces with REST and SOAP API protocols. Monitoring is supported by analytics and customizable downtime alerts and provides data to enterprises to meet service level agreements (SLAs) and customer expectations. 

“The economy has increasingly become a digital economy and the digital economy has been increasingly becoming an API economy over the past decade,” said said Dr. Paul Cray, Head of Machine Learning and Standards at APImetrics. “The COVID-19 crisis has only accelerated that trend. Global quality standards that are meaningful, quantifiable and measurable are essential to maximizing the value that API creators and users provide across many industries. That’s why the OpenAPI Initiative and APImetrics are such a perfect fit, and I am looking forward to working with OAI on these standards.”

APImetrics is particularly interested in working with OAI around standards that can help with the definition and measurement of Service Level Objectives as well as issues around certification, compliance, conformance and continuous testing and monitoring of APIs.

“APImetrics is a welcome addition to the OpenAPI Initiative,” said Marsh Gardiner, Product Manager, Google Cloud, and Technical Steering Committee member, OpenAPI Initiative. “When the industry works together to address common API description challenges, such as describing SLOs and SLAs, everybody wins.” 

OpenAPI Resources

To learn more about how to participate in the evolution of the OpenAPI Specification:

Join us for ASC 2020

Register now for the 2020 API Specifications Conference, Sept 9-10

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

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

ASC Speakers Announced!

By Blog

The 2020 speakers have been announced, and their talks cover the spectrum of expert technologists, business professionals, open source contributors, and more! Learn from companies and organizations like GitHub, Google, Microsoft, MuleSoft, OpenTravel Alliance, Postman, SmartBear, TravelPort, Vonage, and others. Some highlights include:

Dealing with legacy systems? Go through “From 0 to OpenAPI: Describing a 10-year old API with OpenAPI @ GitHub” by Marc-André Giroux and Andrew Hoglund, GitHub

Want to learn about timing pandemic-helping techniques? Take in “All the Interoperability, But None of the Contact” by Jeff ErnstFriedman, OpenTravel Alliance

Sneakily fascinated for the inside scoop of how Postman dogfoods their own tech? Attend “How Postman uses Postman to Build APIs” by Joyce Lin, Postman 

Curious about how to implement a unified API design process that goes beyond adopting a single API style or specification? You definitely want to check out “GraphQL, gRPC and REST, Oh My!: A Method for Unified API Design”  by Mike Amundsen, Inc.

Hungering to inject delight into the developer experience? Perhaps “Create Delightful SDKs from OpenAPI” by Lorna Mitchell, Vonage, is your cup of tea.

Increase your skills, meet your peers, get a look into the latest research and latest real-world case studies. ASC 2020 is a virtual conference this year, being held Sept 9-10. 

Check out the full schedule now!

Register today!

ASC 2020 - API Specifications Conference - Virtual Experience, September 9 - 10. Hosted by the OpenAPI Initiative