What is OpenAPI?
There is the OpenAPI Specification (OAS), a technical specification that describes certain APIs, and there is the OpenAPI Initiative (OAI), an organization that enables specifications like OAS to thrive.
The OAS defines a standard, programming language-agnostic interface description for REST 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. When properly defined via OAS, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OAS removes guesswork in calling a service.
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 based on the rebranded Swagger 2.0 specification, donated by SmartBear Software in 2015.
What is ASC?
Every year the OpenAPI Initiative sponsors the API Specifications Conference (ASC). If you are interested in developing, managing, selling, or using APIs, this conference is for you.
OpenAPI Specification (OAS), RAML, Blueprint, gRPC, OData, JSON Schema, GraphQL, AsynchAPI and other formats will all be topics at the event, enabling attendees to get familiar with these formats and discuss how to use them in practice.
The event has its origins in the API Strategy and Practice Conference (APIStrat) which ran for many years and became part of the OpenAPI Initiative in 2016. The collaborative spirit and community from APIStrat continue through the ASC event and we look forward to many of the same lively conversations and debates!
When is OpenAPI Specification 3.1.0 available?
It’s available now! It was finalized and published February 16, 2021. This newest version supports 100% compatibility with the latest draft (2020-12) of JSON Schema.
Along with this release, the OpenAPI Initiative has sponsored the creation of new documentation to make it easier to understand the structure of the specification and its benefits. It is available here: https://oai.github.io/Documentation/
There is also useful information on Migrating from 3.0 to 3.1.0 here.
How is the OpenAPI Specification different from Swagger?
The OpenAPI Specification (aka the Spec) was originally based on the Swagger Specification, donated by SmartBear Software. Once the Spec was donated it became a separate project in 2016, overseen by the OpenAPI Initiative, an open source collaboration project of the Linux Foundation. For a more detailed (though not “official”) overview of the history of the Spec, please see “Bridging Systems and Subcultures: A Swagger Origin Story”
How is the OpenAPI Specification different from GraphQL?
How are screws better than nails? Both are useful tools that solve similar problems in slightly different ways. OpenAPI Specification offers a declarative contract that defines the structure of API requests and responses as discrete operations. GraphQL prefers an interface style that is more like querying a database and is best suited to graph databases.
Both OpenAPI and GraphQL are Linux Foundation projects.
Where do I get the OpenAPI Specification?
To read the specification, you might start with the latest documentation.
To participate in the on-going evolution of the OpenAPI Specification, visit the project on GitHub.
What are the main benefits of the OpenAPI Specification?
Business benefits are:
- The OpenAPI Specification (OAS) is backed by an impressive group of industry leaders, representing strong awareness and mindshare in the industry.
- OAS is widely recognized as the most popular open source framework for defining and creating RESTful APIs, and today tens of thousands of developers are building thousands of open source repos of tools leveraging the OAS.
- This wide level of industry support is also a strong indication of stability across a substantial and diverse code base today and suggests a promising future.
Technical benefits are:
- With the OAS’s declarative resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code.
- OAS is language-agnostic.
- OAS has great documentation, support, and individual experts who are involved in the community. OAS not only has broad industry support, but it has a long history with a large, energetic, talented community and support base. There are many ways of connecting with talented individuals to find example implementations, code snippets and specifical answers.
Who founded the OpenAPI Initiative and who are the current members?
In November 2015, SmartBear, 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, and Restlet announced the formation of the OpenAPI Initiative (OAI), formed as an open source project under the Linux Foundation.
Today the Initiative includes more than 35 members across a wide group of industry leaders. See the current, complete members list.
How do I join?
Do I need to be a member to participate?
All are welcome to participate. To join the conversation:
- The main action is at https://github.com/OAI/OpenAPI-Specification .
- Sign up for notifications for weekly discussions on Zoom.
- Email firstname.lastname@example.org to get an invitation to join our Slack Workspace.
Do you have any Special Interest Groups (SIGs), and how do I find out more?
We definitely have SIGs, and we encourage you to join in!
- sig-codegen: Slack
- sig-finance: repo | Slack | post
- sig-formats: repo | Slack
- sig-lifecycle: Slack
- sig-overlays: Slack
- sig-security: repo | Slack
- sig-sla: Slack
- sig-travel: repo | Slack | post
- sig-workflows: repo | Slack
How do I submit a blog post?
The OpenAPI blog serves as a channel for the members and the community at large to broadcast to a wide audience how your work and engagement is growing opportunities for the OpenAPI Initiative and the OAS (OpenAPI Specification). Accepted blog posts are at the sole discretion of the OpenAPI Initiative, for guidelines see here.
I have a question and I’m not sure who or where to ask?
We would enjoy hearing from at email@example.com .