It’s not an understatement to say that OAS (OpenAPI Specification) has changed the way many developers design their APIs, with its standardized format allowing for easier adoption and implementation of APIs.

However, the verb used in that last sentence is telling: it talks about how developers “design” their APIs, rather than how they “power” or “utilize” them. At our 2019 Austin API Summit, Vincenzo Chianese of Stoplight spoke at length about how developers could implement the OpenAPI Specification in more involved ways.

What if, for example, it could be used to drive production software with an API Gateway? Below, we’ll be looking at how something intended for standardizing design might be used in the production and implementation of APIs as well.

OpenAPI, DevOps and Automation

First things first, let’s take a quick look at clarifying the terms we’ll be using throughout this article:

“The OpenAPI Specification 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.”

In other words, OAS aims to standardize elements of API production in the hopes of simplifying their consumption. OAS’s official literature goes on to specify that:

Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases.

Note the introduction of automation here, which is something that appears again in information about the concepts behind DevOps:

DevOps is a set of practices that automates the processes between software development and IT teams, in order that they can build, test, and release software faster and more reliably.

Immediately, we see some correlation between the aims of OAS and DevOps: automation, consistency, and improved communication between different parties. Perhaps this is what caused Vincenzo to look at OpenAPI and wonder “what about the operational side of my API?”

OpenAPI & Gateways

For such use cases including…

• Safely rolling out a new API section
• Setting an API section as deprecated
• Changes in security requirements
• Changes in validation rules
• Redirects

…Vincenzo immediately thought about turning to an API Gateway. “That’s usually the best place to do this kind of automation,” he says, highlighting some of the reasons that this felt like the place to dabble with OpenAPI and DevOps:

• Limited configuration surface of API Gateways
• Almost 1:1 match with OpenAPI description file
• Some solutions can be declaratively configured

When it comes to proprietary services, there’s some variation in the extent to which providers line up with OAS. Vincenzo explains, for example, that “AWS API Gateway supports a lot of use cases that you can’t express with OAS, so they have a lot of extensions.”

That isn’t necessarily the case for other API Gateways, though, as Microsoft API Management has a few extensions while Apigee Edge has no documented extensions. This in itself could be useful for helping you determine which gateway is the most suitable for you, depending on how closely you want to stick with OAS.

In the open-source realm, however, Vincenzo says that things are not quite so rosy. He declares that for now, at least, “OpenAPI isn’t a first-class citizen when it comes to Open Source API Gateways” such as Express Gateway, Kong, or Tyk.io.

He pegs flaky/inconsistent support when using them as one reason for this (though acknowledges some recent improvements here), as well as the fact that they’re not the right tool for the job when OAS doesn’t cover certain desired functions.

Interestingly, this may have some parallels with tightly controlled APIs conforming to the recommendations of OAS, while some more out of the box thinking is required with public open-source APIs due to their collaborative nature.

Is OpenAPI Enough?

Vincenzo shares a brief experiment during his talk, in which he makes tweaks to how an API functions. One of the notable things he highlights after the demo? “I didn’t have to touch a single line of code; this is not code that I need to change, but a declarative thing that I need to take care of.”

For some, that will be welcome news. It certainly harks back to the idea of “building a culture of collaboration between teams that historically functioned in relative siloes,” which is one of the core concepts of DevOps.

To maximize the effectiveness of using OpenAPI in tandem with DevOps, Chianese recommends that you:

• Use an API Gateway
• Make sure your API exposes exactly what’s available in the OpenAPI file
• Use a declarative solution
• Refrain from using customer extensions

However, when concluding his talk, he spoke about the limitations of OpenAPI. Specifically, he says that “OpenAPI documents alone aren’t enough to describe all the aspects of an API.” His suggested solution? That the OpenAPI Specification needs to be expanded.

Unfortunately, widespread adoption of OpenAPI means that this solution sounds a lot simpler than it actually is…

The Trouble With Expanding OpenAPI

When it comes to expanding on OpenAPI, users have one of two choices:

1. Wait for the creators of OpenAPI to build on the existing specification – roll-on OAS v4! – to cover the necessary ground (but the open-source nature of the spec means even this is tricky).
2. Build on the specification in a way that suits them, knowing that “official” additions to OAS may look different to the rules and formats they have implemented.

Neither of those is an ideal solution and explains why consistency remains difficult to find even among APIs that conform to OpenAPI for the most part.

A major issue here is that OAS is already considered very comprehensive by most, and to expand the specification further could seem restrictive. This is something that, for obvious reasons, SmartBear wants to avoid: the more restrictive a framework is, the more developers eventually feel the need to deviate from it.

As time goes by, OpenAPI continues to evolve, and the specification will adjust to concepts like DevOps as necessary. In the meantime, it remains a game of experimentation and testing. Still, there are plenty of API developers out there who would argue that’s always the most exciting stage anyway.