Technology can only reach the masses if there’s supporting pieces of innovation. Take the iPad for example. While the concept of a tablet had existed for years before the iPad’s release in 2010, Apple was able to be successful with the iPad partly because of the ubiquity of WiFi connectivity during the time.

If the ubiquity of connectivity could make tablets a reality, the ubiquity of description formats make APIs commercially successful. The OpenAPI Specification (OAS) has emerged as the world’s standard description format for restful interfaces. The OpenAPI Specification is the human-friendly, machine-readable interface for your REST APIs. The OpenAPI Specification describes what the API does, which includes the resources the API exposes, and their corresponding requests and responses.

The format has made accessibility and collaboration between the API’s internal stakeholders, and its external consumers. Simply put, the OpenAPI Specification has changed the way APIs are built and delivered.

The OAS is governed by the OpenAPI Initiative (OAI) under the Linux Foundation. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor-neutral description format.

I had the chance to speak with Darrel Miller, a member of the Technical Steering Committee (TSC) of the OAI, at this year’s API Strategy & Practice Conference, APIStrat 2017. Darrel shared valuable insight into the current state of the OAS project, and how the industry has embraced the latest version of the specification, OAS 3.0.

The Current State of OAS 3.0

OAS 3.0 was released earlier this year? What is the feedback you're getting so far?

The feedback has been incredibly positive so far! We got some nice clean-up and reorganization of the structure just to make the Specification a bit more readable. It’s gratifying to see that some of the changes we've made in OAS 3.0 align us more closely with the way HTTP works and enabled many developers to realize its full capabilities.

We do get a number of people who are excited about the WebHooks and the Links capabilities. The Links capabilities was a really interesting wild card. I think there's a possibility to do a ton of cool stuff with it. Many people falsely assume that we tried to embody hypermedia, and it’s always an interesting conversation with people, especially with my background in hypermedia, around Links.

OpenAPI Spec 3.0 is addressing a real need for companies who like to build APIs using static design principles and define relationships between the operations and the resources in their API. It's definitely become a critical piece of infrastructure.

I think OAS 3.0 has the possibility of vastly improving documentation for APIs as well, because all of a sudden, you now have the possibility to describe flows through the API. I think scenarios are a much better way of describing and documenting APIs, and Links help us go down the path where documentation automation between flows can become a reality. I'd love to see some of the tools people are going to build around that.

I'd personally love to see some richer API documentation use-case and better relationship handling between resources.

I mean you go to an API, how do I use it? Well where do I start? There's 150 resources and a big long alphabetical list, and you've got to start looking at the path structure and decide what does that mean and try to make inferences from that. Whereas, if you could actually tell your consumers, "Well look here are your starting points, and from here you can go and request information."

You're not required to follow that path. You can jump to those end points, but at least for understanding how the API is put together it's a significant addition of semantics to how the API is structured.

Adoption is a huge component of any technological endeavor. How is the OAI educating and spreading the word about OAS 3.0?

I don't think you want to do a really broad push too early while tooling support is still not mature, but it's been great to see the adoption so far. We realize that the only way the OAS can get mass adoption is through more tooling support. We have an implementations page on the GitHub project which lists all the tools that support OAS 3.0. It’s very exciting to see this list grow every day.

We're seeing a nice spread across different technologies when it comes to tooling around the OAS; from Ruby and NodeJS to .NET and JavaScript.

To further support our marketing initiatives, we’ve contracted a marketing and branding company to promote awareness of the OAS. We’ve also thought about advocacy, but I think it' a little early for this as we're still in the process of making sure that we get all the right tooling to support all the features the OAS has to provide.

APIStrat 2017 was the first major event sponsored by the OAI. What did you notice in this year’s edition of the conference?

There's obviously been more of an emphasis on OpenAPI at this year’s APIStrat. I'm hoping that's more just because in the last 12 months, we've had the release of the new version of the spec and there has finally been consolidation of all the people’s consensus in the API space around the OpenAPI being the REST interface’s standard description format. I think we all know the value of having API descriptions and finally we can stop debating, which is the best format. We can actually start getting more and more tooling into the ecosystem around it.

The Evolution of the Specification and Tools

With different organizations so heavily invested in the OAI, how has this enhanced the processes of evolving the spec?

It hasn't changed that significantly at all. The OAI was architected to ensure everyone voice in the community is heard. When member companies join the organization, they're basically making a public statement that they stand by the OAS, as opposed to having influence in its evolution. The membership of the OAI is completely independent to the technical side of the building of the spec itself.

Anybody in the community that has any skin in the game with the regards to API can contribute as much as they want. You don't need to be a member to contribute to the spec, just like you don't need to be a member to read, consume and benefit from the spec.

Having the industry companies come and join the OAI is great for momentum, gaining visibility in the space and establishing the credibility of the OAS. From a technical stand point however, it doesn't have any a direct correlation. The important thing from a technical prospective is getting more people onboard. We are going to focus on trying to get some more core people into the steering committee. There's already many people who have contributed extensively to the project, and we're hoping to nominate and invite this people to join the steering committee. This would allow them to have a little more say in exactly what does go into the spec and help us reach out to more community members to get more input.

To allow more people to contribute, we've taken some time after finishing OAS 3.0 to do some housekeeping and get our governance stuff in order. We are working on developer guidelines to make it clear to people who want to contribute on the kind of process we recommend.

The original version of the spec, the Swagger Specification, was incredibly popular due to the multitude of tools that existed. Moving forward does the OAI have any plans to maybe partner with more vendors?

We're always doing whatever we can to encourage more people to build tools and there are members of the OAI who are in the process of building tools. We have a fairly strict separation between what the role and responsibilities of the OAI is and tools. We are only behind the governance of the specification. We don't want to be in the business of the official organization having its own tooling. It's all third-party tooling; we are just in the business of creating the spec.

So far, we haven't needed to convince people to build tooling, since there’s an organic development of tools from companies. A lot of that is just an update from the already existing tooling in the ecosystem. It was just a matter of we needed to finish the spec and people needed time to absorb it and be able to demonstrate the value in moving to 3.0.

In the blog post published on your website, you mentioned you were skeptical about OAS initially. Did you ever think you’d eventually be working with the OAS?

No, I never in a million years expected to be in the OAI. I say it on the panel as well that it’s not about the correctness of an architectural pattern from a technical perspective, but it’s implications on the workflow of real people. From my blog post, you’d have seen I was, and still am an advocate of hypermedia.

When you have a statically designed API using the OAS, you get certain benefits — like being able to generate documentation scaffolding and generating clients — but lose out on a certain amount of flexibility, which forces you to have a versioning strategy to evolve over time.

It's a tradeoff between static and dynamic design, and I guess at some point I realized I would much rather be part of the solution to help the vast majority of developers build better APIs even though they've chosen a versioning path rather than an evolvability path.

The vast majority of companies are taking the simpler approach and leveraging the benefit of having the static API descriptions. I'm very happy that I'm involved in this initiative, which companies are deriving a ton of value from. Anything that I can do in guiding the future of the OpenAPI Specification so we can avoid certain pit falls then I'm glad that I can be part of it.

Do you think the OpenAPI will ever evolve to support other frameworks or architectures like GraphQL?

HTTP is designed to have extensibility points and the one of the ways it manifests itself is in the form of media types. Webhooks is awesome because webhooks just fits naturally into the HTTP model.

GraphQL defines a set of things that could very naturally be media types. A media type for a query, a media type for a structural response etc. they have their own type systems. That's cool if the existing type system didn't meet your needs.  The web has been massively successful because it has this really nice separation of concerns between the requests, between the resources that you've described on your hierarchy and the payloads which you can send back that are completely independent.

Bringing this back to what the OAS can do, if any architectural style had been built to fit nicely into HTTP rather than trying to layer over the top of HTTP, it’s a fit for OAS. I love innovation and that people are doing stuff. GraphQL could have fit very nicely into that and played alongside of all our existing technologies. What I would really love to see them do is build it in a way that fit more naturally with the HTTP ecosystem.

The other only major style I can see fitting into OAS is an RPC type of APIs where you’re effectively tunneling the operation as part of the request body. This is still a challenge for us because we identify operations using the path. It's a debate I've had over and over in my head as to how we should make operations be identified by something other than the path. For example, in OAS 3.0, we have this new runtime expression, which could be leveraged. Now, I'm not sure how that would even work because then you'd have a whole bunch of operations all with that same run time expression. It could have different operation IDs to uniquely identify those operations, maybe? But the question is at that point are we getting too far away from the way HTTP works?

There are some really interesting conversations to be had there, especially around how we broaden the scope of what we can support without starting to pollute the spec with stuff that not everyone finds value in. If you start doing those kind of adjacent RPC things it kind of feels icky, although I'd love to find a way of supporting people who want to design an API in many ways.

So you just told us that any new feature that the OAS wants to support needs to fit into the way HTTP works. Is usability of these features a consideration as well?

I mean it's critical for adoption, right? I credit Tony Tam (creator of the original Swagger Spec) for incorporating a lot of that into the spec. He would always push back on anything that had to be overengineered or seemed too complex for the end user.

We're now getting people who aren't full-time developers to start designing and building APIs, so having a description format that’s easy to use becomes mission critical. I've actually had conversations with people at OpenAPI meetups who are business analysts and product managers, and not seasoned developers. They may not have the best idea about implementing the API, but they understand the business case scenarios the API should cover.

Closing Notes

I want to end this conversation by knowing the things that excite you most moving forward in the API space?

I want to see what people do with links and documentation using OAS 3.0. API documentation can become incredibly hard, almost to a point of being painful. I'm hoping that somebody with far more technical writing skills, and far better UI knowledge than I would ever could have to take what we’ve built with the OAS, run with it, and create documentation scaffolding generators that are scenario based.

Generated documentation can only take you so far, but scenario-based scaffolding can take the monotony out of producing a lot of consumable information. I that's one of the things that interest me most.

Then we could just go in and add extra bits of value on top of what’s generated. It’s definitely an interesting space to be in, and I’m very excited for the future.

Interested in getting started with OpenAPI 3.0? Check out our free training: OpenAPI 3.0, And What It Means for the Future of Swagger