OpenAPI Initiative

The Open API Initiative (OAI), a Linux Foundation project created to advance API technology, announced the 3.0.0 release of the OpenAPI Specification. The OAI provides a foundation for developing interoperability of APIs and other technologies.

The OpenAPI Specification (OAS) v3 release is the culmination of nearly two years of collaboration among senior API developers and architects from across multiple industries, such as payment and banking, cloud computing, the Internet of Things, and vendors building API solutions. Under the auspices of the OAI, this collaboration provides a common way to unify how an industry defines and describes APIs—the services fundamental to how applications talk to each other in today’s connected world. The OpenAPI Specification defines the interfaces for RESTful APIs, describing resources and operations in a format that is easily discoverable and understandable by both machines and humans.

“The release of this third-generation format is a significant milestone for our community,” said Ole Lensmar, CTO, SmartBear Software and Chair of the OAI Board. “The updates made are entirely user and usage driven and that plays a huge role in the success of the specification. One of the most powerful things about this release is its ability to drive the full API lifecycle.”

Major improvements in the new version 3 release include support for describing callbacks, links to express relationships between operations, webhooks, enhanced examples, improved parameter descriptions, and better multipart document handling. Additional features add support for templated server URLs and semantic versioning. A detailed list is available here: OpenAPI Specification v3

“We’re excited to see growth in adoption and validation for a common OAI Specification, with nearly 4X growth in member companies over the past 18 months alone and increasing interest from governments and the healthcare and fintech sectors,” said Linux Foundation Executive Director Jim Zemlin. “Such growth validates the community’s vision to deliver an open way to share data with APIs.”

APIs have been elevated from a development technique to a driver of business, necessary for technology innovation and modernization. According to ProgrammableWeb, nearly 18,000 public APIs have been published since 2005, up nearly 1,000 in the past quarter of 2017 alone. Founded in 2015, the Open API Initiative has swelled to 27 members in the last 18 months and continues to accelerate beyond API vendors to include leaders in banking, healthcare, and governments worldwide.

Industry Support for OAI

42Crunch
“42Crunch is honoured to be part of the Open API Initiative,” said Philippe Leothaud, Chief Innovation Officer at 42Crunch. “The OpenAPI Specification is open source, platform-agnostic, vendor-agnostic and extensible. Leveraging this de-facto standard will accelerate API adoption across all industry verticals and, in particular, help the automatic consumption of APIs from applications and devices.”

Hart
“Healthcare is going through a data revolution right now with APIs at the top of the agenda,” said Mohamed Alkady, President at Hart. “By agreeing on a common API structure that allows anyone to quickly help build this future without having to re-learn a new nomenclature every time. With the release of OAS3 we are getting closer to a more well defined structure that can be more universally usable and deployable. We believe the Open API Initiative and joint technologies will lead to next-generation changes in API development and we’re excited to push this initiative forward in the healthcare space.”

IBM
“The OAI has progressed this specification relatively quickly, and the IBM Cognitive Cloud and API Economy teams are set to embrace this new, open specification”, said Todd Moore, VP of Open Technology, Digital Business Group at IBM. “By helping to establish the OAI, IBM joined with other companies who understand that robust, scalable, and secure APIs for enterprise systems form the basis of modern digital ecosystems. In addition, today’s software developers want open tooling to help them quickly and consistently create APIs to accelerate business transformation. Our clients trust IBM to help them manage their entire API management life-cycle.”

Kong (Mashape)
“Kong is the world’s most popular open source API gateway, and we’ve seen incredible growth of OpenAPI Specification usage,” said Marco Palladino, CTO and Co-founder, Kong (Mashape). “API specifications are a critical part of modern API development, publishing, and consumption workflows – and the Open API Initiative has been tirelessly advancing the industry-leading OpenAPI Specification format to its milestone 3.0.0 release. We are excited to keep contributing to the tooling ecosystem around OAS.”

Microsoft
“Microsoft congratulates the Open API Initiative and its developers on the release of version three of the OpenAPI Specification,” said Kamaljit Bath, Principal PM Manager, Azure Developer Experience. “We use OpenAPI across the company including: for description of Azure APIs and generating client libraries using the AutoRest tool, for describing over 150 services integrated with Azure LogicApps / Microsoft Flow, for customers to describe APIs they’re bringing to the Azure API Management service, and for description of APIs for which we generate documentation hosted on https://docs.microsoft.com/ and https://apidocs.microsoft.com/. We look forward to the latest release and the improvements it brings for ease of authoring, maintaining, and consuming OpenAPI descriptions.”

MuleSoft
“This new version of the OpenAPI Specification (OAS) incorporates important advances in describing APIs more fully, ” says Uri Sarid, CTO, MuleSoft. “API specifications are central to enabling robust, productive, and rapidly growing marketplaces of business capabilities. These marketplaces, in turn, are at the heart of digital transformations in enterprises, in governments, and across entire industries. OAS version 3 provides a broad format for describing APIs, RAML provides a powerful format for modeling APIs, and the API Modeling Framework leverages both to provide reusability and consistency and a universal SDK for building API tooling. We look forward to continuing to invest in these and in advancing OAI standards to create value for the API ecosystem.”

Red Hat
“Red Hat is a strong believer in Open Standards and Open Source,” said Steven Willmott, Senior Director and Head of API Management, Red Hat Inc. “The progress of the Open API Initiative and this release show what the power of community can do and we are pleased to see the industry coalescing around a strong common standard.”

SmartBear
“SmartBear is a strong supporter of open source communities, having donated the original Swagger Specification to the OAI in 2015. The evolution of the spec shows the power of bringing together collaborators across industries, to evolve the specification to meet the needs of API developers and consumers across the world in an open and transparent manner,” said Ron Ratovsky, Swagger Developer Evangelist, SmartBear. “SmartBear is committed to supporting the OAS 3.0 with our open source Swagger tools and our integrated platform, SwaggerHub.”

Tyk Technologies
“An increasing number of our customers are adopting the OpenAPI Specification as the de-facto API description format,” said Martin Buhr, CEO and Founder of Tyk Technologies. “As a leading Open Source API Management platform, Tyk is committed to open source and open standards, and we’re excited to be part of the OAS v3.0 specification launch.”

Current members of the OAI include: 42Crunch, Adobe Systems, Inc., API Evangelist, Atlassian, CA Incorporated, Capital One, Cloud Elements, Finxact, LLC, Google, Inc., Hart, IBM, Intento, Inc., ISA Research Group, Mashape Inc., Microsoft Corporation, MuleSoft, Oracle Apiary, Red Hat, RepreZen, Restlet, Inc., Salesforce, Samsung ARTIK Cloud, SmartBear Software, Software AG, StopLight, and Tyk.

OpenAPI is an evolution of the Swagger specification, which was donated by SmartBear to The Linux Foundation in 2015. To get more information about the OpenAPI Specification and learn about membership and contributions, please visit: https://www.openapis.org/

Resources:

The OpenAPI Specification v3
Follow OAI on Twitter @OpenApiSpec or join the conversation on GitHub

About the Open API Initiative
The Open API Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing on how REST 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. Visit https://www.openapis.org/ for more information.

###

The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see its trademark usage page: https://www.linuxfoundation.org/trademark-usage. Linux is a registered trademark of Linus Torvalds.

At the OAI Meetup on Sept 15, Jeff Borek of IBM took the audience on the journey the Open API Iniative has taken over the last 9 months. Starting with a brief overview of the Open API Initiative, some background on the Swagger Project that it’s based upon, and ending on how many companies today are collaborating to enable open governance of the OAS 3.0 Spec – as it approaches completion later this year.

LIVE on #Periscope: Open API Initiative Meetup! Jeff Borek, IBM https://t.co/ObDaBaBe9x

— OpenAPI Spec (@OpenApiSpec) September 16, 2016

Before the precursor to the OpenAPI Spec – the Swagger Specification – was created in 2010, Google had already published 150 public APIs, leveraged by hundreds of thousands of developers and handled many, many billions of calls … every day.

At the Sept. 2016 OAI Meetup, Dan Ciruli discusses why in a product post mortem the API team was lead to an open source solutions and eventually join the Open API Initiative.

After getting the details on why they joined, hear what they are doing with it. On Sept. 1, Google announced the open beta release of the newest set of features and open source components in Google Cloud Endpoints. Find out why Google is committed to leveraging the OpenAPI Specification and what they are cooking up next.

LIVE on #Periscope: Google and OAS https://t.co/OAD3VQLErn

— OpenAPI Spec (@OpenApiSpec) September 16, 2016

Slides from Dan’s presentating can be found here:

Statically defined processing in your API stack is so last year. Learn about the the new and interesting ways Capital One is using the OpenAPI Specification to enable more flexible and open API development.

Follow along with Capital One developer Leonhardt de Waal as he zips through the OpenAPI Specification.

Note: Due to technical difficulties, we, more so the project’s PM, but we’ll forgive him this one time, the presentation cut out and is in two parts. We apologize for the inconvenience.

Part 1

LIVE on #Periscope: Capital One and OAS https://t.co/sYqhxHVFMq

— OpenAPI Spec (@OpenApiSpec) September 16, 2016

Part 2

LIVE on #Periscope: Capital One and OAS https://t.co/1mDUN6Xlhq

— OpenAPI Spec (@OpenApiSpec) September 16, 2016

 

Watch a recording of IBM developerWorks Open where OAI Board member Jeff Borek (@jeffborek) moderates a discussion with fellow OAI members Capital One’s Dennis Brennan (@dennis_brennan), Apigee’s Marsh Gardiner (@earth2marsh) and Tony Tam (@fehguy) of SmartBear Software along with Raymond Feng (@cyberfeng) of StrongLoop.

 

Links

• Charts – Open API Initiative at 6 months
• Transcript – Open API Initiative at 6 months
• Q&A – Open API Initiative at 6 months

Last year, I was disappointed to miss out on Gluecon. My colleagues spoke very highly of it — informative, state-of-the-art, and very non-commercial. I was glad that it worked with my schedule this year, and I was absolutely not disappointed. Eric Norlin (@defrag) does a fantastic job of ensuring that his speakers are immensely varied but have one thing in common: extremely high in quality.

I was also excited because this was first event I was attending since the formation of the Open API Initiative and the renaming of the Open API Specification, and I figured it would get some attention. However, I had no idea exactly how much attention it would get.

Not a session went by in the API track without a mention (or, in some cases…many mentions) of Open API (well…more than a few times a speaker slipped and referred to the “Swagger spec”).

What was most exciting about that wasn’t the rename, of course. The reason that every speaker mentioned it so frequently was that it provided a common language, a single touchpoint we could all refer to for discussing APIs. The goal in forming the initiative was to allow the industry to move beyond discussions of which format is better and why–so we could concentrate on the toolchain and ecosystem possible when we all agree on a common language.

The API track was great. James Higginbotham from LaunchAny spoke on domain-driven design and the importance of abstraction in API definitions. Emmanuel Paraskakis from Apiary.io, Tony Tam from SmartBear (and the Swagger project) and Ray Camden from StrongLoop all talked about improving the speed and scale of your API development workflow. And Guillaume LaForge from Restlet wrapped up the API track with his talk on the “Five Sided Prism Polarizing Web API Development.” (!)

And if a five-session API track on Day 1 wasn’t enough, Day 2 featured no fewer than eight API-related sessions. One of the best moments for me was Mark Stafford’s talk on his Model First project — a framework for composition of Open API specs that helps to enforce consistency and ease development (running here, code here).

But the API-highlight of the conference had to be Stewart Nickolas from IBM’s talk on “Conversational Computing.” His talk was nearly entirely done via voice interaction with Watson…including interrogating Watson about an API, having Watson describe the Open API Spec, and then having Stewart tell Watson verbally to invoke the API.

Somehow, I doubt developers are going to be doing much introspection of APIs verbally in the future. But it remained a very powerful demo especially when I considered that the entire demo was powered, of course…by APIs.

—
About The Author
Dan Ciruli
Dan Ciruli is a product manager at Google who works on API infrastructure. He used to play a lot of ultimate when he had knees and write a lot of software when he had time. He’ll try to speak Spanish to you if you give him a chance. You can find him on Twitter at @danciruli.

Gluecon is just around the corner, and the Open API Initiative is giving a way a free pass. To qualify:

1. Find any open source project that refers to Swagger Specification* instead of OpenAPI, whether as in documentation or in the codebase itself.
2. Update those references to reflect the new name OpenAPI (See this example here)
3. If you are already a collaborator, push your changes. If you’ve forked the project, submit a pull request with your changes.
4. Tweet a link to your work (commit or PR) to @OpenApiSpec along with your GitHub ID

The OAI Gluecon team will select one winner! Getting to Gluecon has never been easier.

*NOTE: This only applies to the specification that refers to Swagger Specification. For a history on the name change click here.

Details: The giveaway is only for an entry pass to Gluecon, attendees are responsible for travel and accomodations.

 

—
About The Author
Marsh Gardiner
At least two of the following three statements are true about Marsh: No one loves APIs more. He is a developer trapped in the body of a product guy. He hates writing bios.

In the semi-random walk of Marsh’s career, he has produced videogames for EA and Fox, created interactive learning environments, launched an educational non-profit organization, and fought bravely in the API wars of 2009-2018. At Apigee, he imagines a better future for apps and APIs.

Our guest post today comes from Brandon Phillips of CoreOS. CoreOS builds open source projects and products for Linux Containers. Their flagship products for consensus and discovery (etcd) and their container engine rkt are early adopters gRPC, an RPC framework based on protobufs and HTTP/2, that can make building and consuming APIs easier and more performant. Since many clients speak http/1.1 plus json, the interoperability with JSON and Open API is very important. For users who are more comfortable with HTTP/1.1+JSON-based APIs and the Open API Initiative Specs (formerly swagger) APIs they are using a combination of open source libraries to make their gRPC services available in that form as well. They have built API multiplexers to give users the best of both worlds. Let’s dive into the details and find out how they did it!

This post was originally published at the CoreOS blog (link). We are reproducing here with some edits.

 

One of the key reasons CoreOS chose gRPC is because it uses HTTP/2, enabling applications to present both a HTTP 1.1 REST+JSON API and an efficient gRPC interface on a single TCP port.(available for Go) This gives developers compatibility with the REST web ecosystem while advancing a new, high-efficiency RPC protocol. With Go 1.6 recently released, Go ships with a stable net/http2 package by default.

A gRPC application called EchoService

In this post we will build a small proof-of-concept gRPC application from a gRPC API definition, add a REST service gateway, and finally serve it all on a single TLS port. The application is called EchoService, and is the web equivalent of the shell command echo: the service returns, or “echoes”, whatever text is sent to it.

First, let’s define the arguments to EchoService in a protobuf message called EchoMessage, which includes a single field called value. We will define this message in a protobuf “.proto” file called service.proto. Here is our EchoMessage:

message EchoMessage { string value = 1; }

In this same protobuf file, we define a gRPC service that takes this data structure and returns it:

service EchoService { rpc Echo(EchoMessage) returns (EchoMessage) { } }

Running this service.proto file through the Protocol Buffer compiler protoc generates a stub gRPC service in Go, along with clients in various languages. But gRPC alone isn’t as useful as a service that also exposes a REST interface, so we won’t stop with the gRPC service stub.

Next, we add the gRPC REST Gateway. This library will build a RESTful proxy atop the gRPC EchoService. To build this gateway, we add metadata to the EchoService proto to indicate that the Echo RPC maps to a RESTful POST method with all RPC parameters mapped to a JSON body. The gateway can map RPC parameters to URL paths and query parameters, but we omit those complications here for brevity.

service EchoService { rpc Echo(EchoMessage) returns (EchoMessage) { option (google.api.http) = { post: “/v1/echo” body: “*” }; } }

In practical terms this means the gateway, once generated by protoc, can now accept a request from curl like this:

curl -X POST -k https://localhost:10000/v1/echo -d ‘{“value”: “CoreOS is hiring!”}’

The whole system so far looks like this, with a single service.proto file generating both a gRPC server and a REST proxy:

gRPC API with REST gateway

To bring this all together, the echo service creates a Go http.Handler to detect if the protocol is HTTP/2 and the Content-Type is “application/grpc” and sends such requests to the gRPC server. Everything else is routed to the REST gateway. The code looks something like this:

if r.ProtoMajor == 2 && strings.Contains(r.Header.Get(“Content-Type”), “application/grpc”) { grpcServer.ServeHTTP(w, r) } else { otherHandler.ServeHTTP(w, r) }

To try it out, all you need is a working Go 1.6 development environment and the following simple incantations:

$ go get -u github.com/philips/grpc-gateway-example $ grpc-gateway-example serve

With the server running you can attempt requests on both HTTP 1.1 and gRPC interfaces:

grpc-gateway-example echo Take a REST from REST with gRPC curl -X POST -k https://localhost:10000/v1/echo -d ‘{“value”: “CoreOS is hiring!”}’

One last bonus: Because we have an Open API specification, you can browse the Open API UI running at https://localhost:10000/swagger-ui/#!/EchoService/Echo if you have the server above running on your laptop.

gRPC/REST Open API  document

We’ve taken a look at how to use gRPC to bridge to the world of REST. If you want to take a look at the complete project, check out the repo on GitHub. We think this pattern of using a single protobuf to describe an API leads to an easy to consume, flexible API framework, and we’re excited to leverage it in more of our projects.

—

About The Author
Brandon Phillips (CoreOS)
Brandon Philips is helping to build modern Linux server infrastructure at CoreOS as CTO. Prior to CoreOS, he worked at Rackspace hacking on cloud monitoring and was a Linux kernel developer at SUSE. As a graduate of Oregon State’s Open Source Lab he is passionate about open source technologies.

The Linux Foundation asked me to do a lighting talk at the Linux Collab Summit at Lake Tahoe earlier this year. I was pleased to speak on behalf of The Open API Initiative and talk about the growing interest in open APIs and the future of the Swagger Project. It’s meaningful that the specification is now under the guidance of this Linux Foundation working group, and we at IBM are excited about the future evolution of the spec and related code base as we work with the project founder Tony Tam and the larger community promoting open API technologies.

Click the image below to watch my 3 minute talk from March 27, 2016. You can also follow me on Twitter: @jeffborek

—

About The Author
Jeff Borek
Jeff Borek (WW Program Director for Open Technology & Partnerships, IBM) is a senior technology and communications executive with over twenty years of leadership and technical experience in the Software, Telecommunications, and Information Technology/Consulting industries. He is currently the business development lead for the Open Technologies and Partnerships team – working with clients, business partners, leading industry analysts, and various open source community initiatives including; the Linux Foundation, the OpenStack cloud software project, and the Cloud Foundry Foundation. He also represents IBM as the current Chair on the Docker Governance Advisory Board, but most importantly for us he serves on the board of the Open API Initiative. You can follow him on Twitter.