Build delightful APIs using the OpenAPI Specification

Standards are awesome.

What kind of world would this be if programming languages allowed () and [] and {} to be used interchangeably or even mixed together? Chaos would ensue.

What if the port on the side of your computer was simply a jumble of loose wires and contacts, waiting for you to find the right combination of connections to power up your webcam? Thank goodness for the USB standard.

APIs need standards, too. Building your application on top of unpredictable and unreliable APIs is a time-killer. It’s just one headache after another. That’s why API development has moved toward broad adoption of the OpenAPI Specification (OAS)— the industry standard used by both builders and consumers of APIs.

How might OAS help as you build systems that consume APIs? What are the pitfalls you’ll avoid by using APIs that adhere to OAS?

Ultimately, an API is most usable when it conforms to a standard. In addition to OAS-conformant APIs being more usable, OAS has led to several tools—like Swagger and APIClarity—built for developers to better understand the APIs they’re working with. Swagger comprises a suite of tools used for the design, development, documentation, and testing of APIs. APIClarity observes real-time traffic to and from an API, and then compares actual usage against the API’s specification.

Let’s look at how the OpenAPI Specification came about and then dive into how adopting OAS will remove the headaches and bring confidence back to your integration of third-party APIs.

What is the OpenAPI Initiative?

The OpenAPI Initiative (OAI) is “a consortium of forward-looking industry experts who recognize the immense value of standardizing how APIs are described.” The OAI consortium members include big hitters like IBM, Google, Oracle, MuleSoft, and Kong.

When establishing the standard, the goal of the OAI is to bring value to developers on both sides of an API.

For developers constructing the API, the standard provides a framework for building reliable services that interact with others. That framework nudges you toward best practices for security and future-proofing your development. The APIs you build can become predictable and reliable. By using a standard format to document your API, your API becomes more discoverable.

For developers consuming APIs, the benefits are even greater: interacting with an API that conforms with a standard provides assurance that the API you use will be predictable and reliable. You also reap the benefit of API discoverability, as APIs documented according to OAS will be more easily findable in API marketplaces or exchanges.

OAI operates under the Linux Foundation as a partnership between many industry-leading companies. Developers and consumers of APIs that adhere to OAS can take comfort in knowing that those APIs are vendor-neutral and rely on well-known web technologies.

OAS itself was initially based on the Swagger Specification and continues to have many elements drawn from Swagger’s popular API documentation tool. Additionally, OAS targets RESTful API development and the resource-driven API model.

Why Use OAS?

When an API is designed, built, and consumed in adherence to a standard, it benefits both the maintainers and the users of the API. There’s no more lost time or guesswork trying to figure out whether the params were supposed to be in the query string or in the request body, or whether authentication in the header was basic auth or bearer auth. Developer confidence and velocity—for builders and consumers increases, since conventions lead to code consistency.

With the OpenAPI Specification, developers enjoy many benefits and avoid common pitfalls.

Benefits enjoyed

One of the biggest benefits of the OAS is the definition of a convention—a standard, language-agnostic interface. OAS-conformant APIs can be implemented in any language and with any number of services underlying them. The specification is completely decoupled from the implementation details of the API which it describes. The specification simply details the function of the API.

This separation from the implementation is a benefit to both developers and consumers of an API service, as it eases the discoverability of different functions of the system. With a specification in hand, an API consumer can easily understand the API without needing to know the language or framework in which the API was developed. Consumers will not need access to any source code or specialized documentation. For example, consumers of the Twitch API would have all they need for API usage from an OAS document, without needing to learn Ruby on Rails or Go, which are part of the Twitch tech stack. Similarly, users of the Spotify API don’t need to learn Python or Java to use the API. This is the benefit of OAS being language-agnostic.

Because the OpenAPI Specification is so widely used and agreed upon across the industry, numerous tools have been built to simplify the task of API development. There are tools to validate requests (such as Dredd or RESTest), automate the writing of API documentation (such as Stoplight or DeveloperHub), and even generate SDK code for many client languages (such as APIMatic CodeGen or OpenAPI Generator). While an API developer can certainly go it alone and build without any assistance, it’s certainly helpful to have many toolchain options when building an OAS-conformant API.

Pitfalls avoided

Additionally, using an OAS-conformant API ensures you don’t fall victim to many common pitfalls. Endpoints across an API are guaranteed to be consistent because the standard ensures the usage of HTTP methods.

You also won’t need to worry about running into deprecated APIs (sometimes called “zombie APIs”), as the standard ensures reasonable versioning of the API. OAS-conformant APIs won’t introduce breaking changes within the same version; instead, breaking changes would require a version change in the API.

Undocumented APIs (or “shadow APIs”) are also avoided when using OAS-conformant APIs, because the standard requires developers to use an understandable and agreed-upon structure in their APIs.

Enforcing OAS Adherence

With all that the OpenAPI Specification promises, it may seem daunting to ensure that the APIs you consume are OAS-conformant. The task of building an API that adheres to OAS may seem equally formidable.

It doesn’t need to be.

To begin with, the tools around the OpenAPI Specification are a huge asset for any developer working in the space. Since OAS was originally based on the Swagger Specification, there are still many tools from Swagger that can help any developer working on an API.

For API developers, the OpenAPI Initiative provides a list of tools useful for building robust OAS-conformant APIs. Whether you need code generation or documentation assistance, there’s probably something for you there.

When building API-consuming client applications, helpful tools include those used for learning more about the APIs you consume. Some of these tools can run against that API you want to use, generating a description of the API according to the OAS standard.

For example, APIClarity is a tool that observes all of the API traffic within your Kubernetes environment. Based on traffic observation, APIClarity infers an OpenAPI description for those APIs.

This is especially helpful if the API creator never defined or provided such a description. It also surfaces potential problems with existing APIs, such as requests made to undocumented, shadow APIs or continued use of deprecated, zombie APIs. If you’re getting started on the path toward OAS compliance, then tools like APIClarity can be a great source of insight and observability.

Conclusion

In summary, the OpenAPI Specification exists to make a developer’s work much easier—whether they build or consume APIs. Rather than making design decisions on the fly based on past experience, you can build on the shared wisdom of industry experts to make a great API or client application. Getting started on building an API using the OAS standard isn’t out of reach and is something you could begin today!

First Published here