OpenAPI Initiative

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.

Here comes a quick update on the ongoings within the OAI:

New Members

There is an ongoing interest in joining the OAI and we are thrilled to welcome two new members to the group:

• Apiary: creators of API design and collaboration tools that recently announced support for Swagger / OpenAPI Spec.
• Atlassian: the people behind JIRA, Confluence, HipChat, Bamboo, etc.

If your organisation is interested in joining the OAI to support the evolution and proliferation of the OpenAPI Specification then please have a look at https://openapis.org/join for details on how to do so.

Initial TDC Memberships and process finalized

The initial members of the Technical Developer Community driving the OpenAPI Specification have been decided on;

• Darrel Miller – @darrel_miller
• Jason Harmon – @jharmn
• Jeremy Whitlock – @whitlockjc
• Marsh Gardiner – @earth2marsh
• Ron Ratovsky – @webron
• Tony Tam – @fehguy

This list of contributors is maintained at on GitHub in line with the OAI charter.

The process for the evolution of the specification has been published by the TDC at https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/DEVELOPMENT.md

OpenAPI Spec 3.0 work progresses

Work on the next major iteration of the specification has started, and discussions on various features/improvements are in progress on corresponding issues at GitHub. If you’re interested in getting informed or involved here are a couple of links to point you in the right direction:

• The OpenAPI.next branch on GitHub
• The list of proposed issues for the next version

OAI represented at events

The OAI will be represented by our members at two upcoming OW2 events in Europe:

• Cloud Computing World Expo, Paris, 23-24 March – Represented by Restlet
• Cloud Expo Europe, London, 12-13 April – Represented by 3Scale

The OAI is currently evaluating it’s possibilities to participate in upcoming API-related events around the globe; if you’re organising an event where you would like the OAI to be represented or if you’re interested in organising a local OAI/OpenAPISpec meetup that the OAI can sponsor – please don’t hesitate to get in touch.

Other ongoing activities

• We have assigned an internal workgroup to provide guidelines on usage of the OAI logo and mark – these will be published on our website.
• The OpenAPI Specification now has a twitter account at https://twitter.com/openapispec – follow it to get notified of both OAI and OpenAPI-Spec related news.

That’s it for now – please don’t hestitate to get in touch with the TDC on GitHub if you’re interested in participating in the technical discussions around the OpenAPI Specification – or with the OAI members via our contact form if you have general inquiries – we look forward to hearing from you.

/Ole Lensmar
@olensmar

Amidst the general ongoing end-of-year activities, the OAI has been busy getting all the initial pieces into place for 2016. The meetings we’ve had within the group during last December have resulted in the following:

1. OADF renamed to “OpenAPI Specification”

The initially suggested name for the harbored specification was OADF (“Open API Definition Format”) – a name that seemingly begged to be replaced by something catchier; the members of the OAI have decided on “OpenAPI Specification” (abbreviated to “OAS”) to be the new name going forward.

2. Swagger Specification repository moved to the OAI on GitHub

The Swagger 2.0 specification repository has consequently been moved from its original location under the swagger-api organization on GitHub to the new OAI organization with the name “OpenAPI Specification” – https://github.com/OAI/OpenAPI-Specification.

The specification itself has not been changed at this point to not break any existing tooling that works with Swagger 2.0 definitions. The next release of the OAS will deprecate any usage of the term “swagger” in the specification in favor of an OAS-specific term; the TDC will be responsible for the implementation of this transition.

The OAS will continue to be licensed under the Apache 2.0 License.

3. New OAI members 

The interest for joining the OAI after its initial launch has been overwhelming  – and we are happy to welcome the following companies to the group;

• APInf – of https://apinf.io/
• Mashape – https://www.mashape.com/

If you or your organization is interested in joining the OAI please don’t hesitate to get in touch with the OAI at https://openapis.org/join.

4. New OAI leadership is taking form

The OAI charter designates 3 entities that form its governing structure:

1. The board of members which set the charter for the group as a whole and manages non technical tasks
2. The Technical Developer Committee (TDC) that is responsible for the actual technical work on evolving the OAS
3. The Technical Oversight Board (TOB) that resolves any conflicts in the TDC and makes sure that the TDC delivers in line with the OAIs core values.

The formation for the TDC and TOB is still in progress; as for now the following persons have been elected:

• TDC members: <still in progress>
• TOB members:
  • Elected by OAI members: Tony Tam, Ron Ratovsky, Jason Harmon
  • Elected by TDC members: <still in progress>
• OAI Chairman: Ole Lensmar

Next Steps

As the OAI is starting to take shape we have the following on our agenda:

• Finalize the TDC and TOB memberships
• Start work on the next version of the OAS within the TDC
• Decide on which non-technical activities the OAI can engage in to facilitate the further evolution of OAS and its adoption within the industry

I’m obviously very excited about what we have ahead of us – the industry momentum behind APIs isn’t showing any signs of slowing down and the need for a common language for API definitions is evident as businesses strive to maximize their usage of APIs to provide value to their end-users.

Happy New Year!

/Ole Lensmar