It's Time For Every API to Have an OpenAPI Spec

In recent years, API specification/description formats have become more common and increasingly useful. These various formats, most notably OpenAPI, standardize the once-murky definition of an API. This standardization allowed the creation of a broad ecosystem of tooling for auto-generated testing and Documentation, in addition to surfacing the fields and types of an expected API response.

OpenAPI has largely become the de facto description format in REST API development. In this post, we'll look at how API definitions are being used and some ways they can improve your organization when you fully build upon them.

APIs Have Come a Long Way

Salesforce, eBay, and Amazon led the way with public APIs in the early 2000s. These "web services" looked very different than what we're used to now. The primary approach was the Remote Procedure Call, XML- RPC, and its predecessor SOAP. In fact, O'Reilly's definitive book, Web Services Essentials, published in February 2002, called SOAP "the foundation for most commercial Web Services development."

Along with SOAP APIs came WSDL, the Web Service Definition Language. If you had the right tooling, you could import the WSDL and make API calls easily from your code editor. However, making calls to SOAP APIs with your typical browser or command line tools ranged from difficult to impossible.

By contrast, RESTful APIs gained popularity due to the relative ease of getting started. As part of the move toward light-weight approaches, JSON became favored over XML. However, early attempts to describe RESTful APIs, such as WADL (Web Application Description Language), depended too heavily on XML.

REST APIs with JSON responses became the de facto standard, without a truly standardized way to define or describe them.

How API Definitions Are Being Used Today

The Industry wanted a way to maintain the lightweight first use of modern APIs while knowing what to expect from requests and responses. Several initiatives tackled the problem, with OpenAPI emerging as a burgeoning standard. Part of the Linux Foundation, the OpenAPI initiative is maintained by a consortium of companies and individuals looking to advance modern API definitions.

In fact, OpenAPI has improved the first impression for many APIs. One of the largest use cases for OpenAPI definitions is documentation. Open source tools and startups began to turn machine-readable definitions into beautiful human-readable documentation. This improvement in clarity means that you can now often make test API calls right from the page, against either live or mock servers. Developers can get an idea of what's possible with many OpenAPI-defined APIs without any tooling beyond a simple browser.

How API Definitions Are Being Used Today - human-readable documentation

There is also plenty of special tooling being built to generate and use OpenAPI definitions. Unlike with previous formats, OpenAPI can be written in JSON or YAML, both easy to read and write by hand if necessary. You can find OpenAPI-specific editors, with both text and form interfaces, to help would-be API providers describe their existing or emerging APIs.

Once you have a definition, either providers or consumers can use it as part of their workflow. You can Parse, validate, and test an API against its OpenAPI definition. Additional tools can help throughout the API lifecycle once you have described your API.

OpenAPI has become the foundation of modern APIs, yet there are still many without proper definitions. Too often, a definition exists, but it is only shared internally. With all the tooling available—including more than can be covered here—it's time that every API provide its own OpenAPI definition.

Look Beyond the API Definition

We have passed the early adopter phase of OpenAPI. If you're serious about API consumption, either publicly or internal to your organization, you should create a definition. You'll be able to generate documentation—and, perhaps, client libraries—from your definition. These time savings alone are enough reason to include an OpenAPI definition. In addition, you get access to many other OpenAPI tools to help you and your API consumers.

However, one thing your OpenAPI definition may not directly describe are the use cases within your API. An understanding of what your software does should be baked into your API. There is always a gap between the intended and actual usage of any piece of software, APIs included.

For example, let's say your API sends physical letters in the mail (believe it or not, several of these exist). You might need one API call to create an envelope with an address, another for each piece of printed paper to include, and finally a call to add the papers to your envelope. You should describe each of these separately in your OpenAPI definition. Next, you want a way to describe the sequence of API calls that encompass this use case.

There are many human-readable ways to turn your API endpoints into use cases. You can write tutorials, developer guides, and other forms of documentation. As we learned from OpenAPI definitions, it's also useful to describe in a way machines can interpret. You can import Postman Collections, for example, to group individual requests together.

Describing your API is the foundation atop which you can generate documentation, explain use cases, and automatically run tests against what you've built. When you combine an API definition with the available tooling, you can create APIs that are easier to use, fulfill your business goals, and maintain reliability. Plus, your API definition is an artifact which can evolve alongside your code.

Be sure to read the next API Description Languages article: OpenAPI Initiative Announces OpenAPI Specification Version 3.1.0