All Posts By

Open API Initiative

TDC: Structural Improvements: explaining the 3.0 spec, part 2

By | Blog | No Comments

With the version 3.0 of the OpenAPI Specification nearing a beta candidate, this series of posts is meant to provide insight into what is changing and how. The first post described the background and rationale behind the next evolution of the spec, and the next few posts will address the progress made by the Technical Developer Community (TDC) so far.

In an effort to organize the work, six omnibus meta-issues have been created:

  1. Structural improvements
  2. Request Parameters
  3. Protocol and Payload
  4. Documentation
  5. Security
  6. Path definitions

Over the next couple of weeks, we will describe each in order. Today, we’ll cover…

Structural Improvements

The next version of OpenAPI will have some pretty significant changes—in semantic versioning terminology, this will represent a major change from 2.0 to 3.0. Since breaking change events happen rarely, they present the opportunity to make sweeping structural improvements.

Most importantly, with the OpenAPI Specification version 3.0, the overall structure of the document has been simplified:

pasted-image-0

New Version Identifier

One obvious place to begin the transition from the description that was once called Swagger 2.0 and is now known as the OpenAPI Specification? The version property that was called swagger from 2.0 will be replaced by an openapi version identifier. Going forward this version identifier will follow the conventions of semantic versioning, and therefore it will have three parts: major.minor.patch, which likely means 3.0.0. This also explains why the value is a string rather than a number, and it will allow for more controlled and identifiable changes to the specification in the future.

Components Objects

OpenAPI 2.0 was somewhat inconsistent in the behavior of root-level properties. For example, some properties contained metadata that was applied globally to the API, while other properties were used as containers for reusable fragments of metadata to be referenced elsewhere. In order to clarify this and to minimize the number of properties at the root level, a new components property will be introduced. This components property contains only reusuable metadata that will be referenced elsewhere in the document.

pasted-image-0-1

Multiple Hosts

OpenAPI 2.0 allowed specifying a single host and basePath, and yet the schemes attribute allows specifying both http and https, therefore effectively enabling two hosts that only vary in the scheme. In the OpenAPI.vNext, the working branch of the spec repo, a new root level hosts object contains an array of objects that contain host, basePath, and scheme properties. By structuring this as an array of objects, any number of root URLs for the API can be supported, and it allows for a clearer correlation of the scheme, host, and basePath properties. It also reduces the number of root level properties required, simplifying the document structure.

hosts

During the discussions around the GitHub issues and associated pull request, the TDC addressed the question of whether paths might be identified as representing different environments, such as dev, test, and production. However, this would have suggested that different hosts might point to different API implementations, and that was not the intent behind supporting multiple root URLs for the API. Rather, the goal was to allow a set of aliases to be defined for the same API. (Note: there remains an open issue concerning parameterization of the host and basePath, which might allow for pointing to different environments.)

Additionally, the host, basePath, and scheme may be overriden at the path item level. This should make it easier to incorporate functionality provided on a separate host into an API description.

pasted-image-0-2

More Descriptive Options

The new specification allows users to describe their APIs in a more resource-oriented manner. Previously, descriptions of API behavior were defined at the operation level. For APIs designed in a resource-oriented way, documentation text would often read “GET a foo”, “POST a foo”, “DELETE a foo”. If the purpose of “foo” needed to be elaborated upon, it became necessary to somewhat duplicate that text for each operation. Now a Path Item Object can contain both a short summary text and a longer description text. The choice to provide additional description at the operation level is left up to the user, based on whether further explanation is required.

Examples Object

The options for describing examples have been significantly expanded. The previous specification indicated that examples could only be described by a JSON or YAML object. Now, by using a JSON string, any format of example can be described. Additionally, a $ref object can be used to point to external files containing examples. The exact method of structuring examples is still in flux and may depend on whether the proposed content object is accepted by the TDC. The content object contains an array of example objects for defining a one or more examples for each media type.

As you can see, this one meta-issue about the structural changes has a lot to digest. The next post will discuss changes to how requests are described in OpenAPI 3.0.

  • Previous post in this series Part 1 – Background and how to get involved!

 


Darrell MillerAbout The Author

Darrel Miller
Darrel Miller is a Senior Software Development Engineer on Azure API Management for Microsoft. Darrel is a member of the OpenAPI Specification Technical Developer Community. You can follow him on Twitter or on his blog Bizcoder.

Open API Initiative, 9 Months and Counting – OAI Meetup 2016-09-15

By | Blog | No Comments

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.

Jeff BorekAbout 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.

OpenAPI Spec at Google – OAI Meetup 2016-09-15

By | Blog | No Comments

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.

Slides from Dan’s presentating can be found here:


Dan CiruliAbout 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.

Zipping through the OpenAPI with Capital One – OAI Meetup 2016-09-15

By | Blog | No Comments

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

Part 2

 


About The Author
Leonhardt de Waal
Leonhardt is a software engineer at Capital One.

Open API Initiative: Six months and counting (Recording)

By | Blog | No Comments

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.

 Six months and counting

 

Links

You Can Get Involved in Creating the OpenAPI Specification, And Here’s How

By | Blog | No Comments

How is the OpenAPI Specification evolving? What’s the process? How can you get involved? Today we’ll try to answer those questions and shine a light on:

  • The Technical Developer Community, why it exists and how it operates
  • The timeline and roadmap for the next major revision of the OpenAPI Specification

Open API Logo

Last December, the Swagger 2.0 specification was donated by SmartBear and became the OpenAPI Specification (sometimes abbreviated OAS). The spec is 100% compatible, only sporting a new name and brand. Why was this important? In some ways it doesn’t—there was nothing “broken” before. However, in order for sometimes-competitive vendors to build support for the format into their products and to collaborate on an industry standard, they needed a neutral governance model. This is exactly why the Open API Initiative was created under the Linux Foundation in order to evolve what was once known as the Swagger specification.

_meta_issue_specification_documentation_structure_and_supporting_docs_issue_589_oai_openapi-specificationThe Open API Initiative’s charter created, “an open source, Technical Developer Community (TDC), open to any participant, whether an OAI Member or not. ” The TDC is responsible for overseeing the evolution of the OpenAPI Specification. Today, the TDC has six members, and it will grow over time as individual members of the community step up to drive the format. The good news is that ever since the 2.0 specification was launched, people in the community have been offering suggestions for how to improve it. Many of those issues have been identified as candidates for the next major release—the challenge now is to decide what is in or out for the next version and to bring those changes to release candidate status.

In order to tackle the huge backlog of issues, Tony Tam, who founded Swagger and leads the TDC, identified a number of high level themes such as Security and Protocols and Payloads, added references to the individual issues and then tagged them as Meta issues for OpenAPI.Next on GitHub. The single best way to understand the direction that the OpenAPI Specification 3.0 may take is to review those meta issues. Over the next few weeks, Jason Harmon, Darrel Miller, and Marsh Gardinerwill try to break down some of those issues with individual blog posts in order to explain some of the thinking behind them.

clarification_about_yaml_by_fehguy_pull_request_635_oai_openapi-specificationWhile the TDC strives to communicate through issues and pull requests, we’re all volunteers that steal time to work on OpenAPI. Sometimes it’s faster to have an hour long conference call, which we do every couple of weeks. In addition, we use the OAI’s Slack team to raise attention to questions or suggestions when GitHub notifications don’t get the job done. The changes proposed by a sub-issue in a meta issue result in a pull-request (PR), and that PR is then voted on by using a reaction on the issue.

How can you get involved? If you have a particular interest in a topic, search the existing issues and join the conversation or start one if necessary.

Some of those topics are philosophical, such as Is OpenAPI an Open World or Closed World Contract?Some of them are passionate, such as Support for multiple request/response models based on headers. Other topics go deep into questions about JSON-Schema or the YAML specifications. Over the next few weeks, we’ll post here on the blog about some of the meta-issues and sub-issues and give some insight into the nature of the discussions around them.

 


Marsh GardinerAbout 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.

Gluecon Wrap up: Living Up to the Hype for a First-Timer

By | Blog | No Comments

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.


Dan CiruliAbout 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 Pass Giveaway!

By | Blog | No Comments

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.

 


Marsh GardinerAbout 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.

gRPC with REST and OpenAPI Specification

By | Blog | No Comments

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-rest-gateway

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.

Swagger browser screenshot

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.

Brandon PhillipsAbout 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.

State of the Project Update with Jeff Borek at the 2016 Collaboration Summit

By | Blog | No Comments

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
Jeff Borek of IBM at Collaboration Summit 2016

Jeff BorekAbout 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.