API Academy

Sponsored by Layer7

A man sitting in front of a laptop computer.

Modern API Description Formats

By Adam DuVanderPosted on

For many organizations, the days of undocumented APIs are mostly gone. There are now several formats used to describe APIs. These machine-readable files can be converted into documentation and even be used to test integrations. While there are several formats, the most well-known is OpenAPI. In this article, we’ll provide a highlight of that and several other methods companies use to define their API functionality.

Industry Standard is OpenAPI (Not Swagger)

Officially started in 2015, the OpenAPI Initiative is a vendor-neutral open source organization. The 2017 OpenAPI Specification defines a standard, programming language-agnostic interface description for REST APIs. The OpenAPI Specification is the successor to the Swagger Specification, which started in 2011. 

OpenAPI is supported by more than 30 companies including Microsoft, Google, and IBM. While support helps make a standard viable, tools make it useful. There are open source and proprietary tools built to create, consume, and expand upon OpenAPI.

For example, you can generate documentation, mock servers, and code stubs from a description, which can decrease development time. Similarly, you can use OpenAPI to enforce API governance or run integration tests against a live or development API. 

Other Popular API Definition Formats

Along with OpenAPI, there are other common formats within API documentation:

  • RAML: RESTful API Modeling Language focuses on re-usable models within the API with human-readable YAML format (similar to OpenAPI, which also supports JSON).
  • API BluePrint: focuses on design collaboration and allows entire teams to write their API documentation together.
  • Postman Collections: focuses on describing API interactions, which can then be automatically tested. . 

Some of these may be used as alternatives to OpenAPI or to augment it. The same can be said for some of the more recent API formats, like AsyncAPI and GraphQL.

The Future of API Descriptions

Given the traction of these “up-and-coming†formats, the future is already here. Where classic REST APIs have not quite hit the mark, new API approaches emerged. In the case of GraphQL, it’s an entirely different approach to delivery. For AsyncAPI, it’s codifying a practice already in place.

AsyncAPI builds off of OpenAPI to improve on describing APIs that use Event Driven Architecture, or Asynchronous APIs. Rather than making a client request new data, this approach proactively sends data as it is available. AsyncAPI helps define the pattern—and what data developers can expect from an API.

GraphQL, on the other hand, is a query language for APIs as well as a server side runtime for executing queries. Most RESTful APIs pre-determine what data is included in the response, but modern interfaces need more flexibility. GraphQL allows users to create queries for the exact data they need, providing smoother collaboration between front and back-end developers.

Both of these formats bring something new to the table, matching technical needs amongst engineers. Along with OpenAPI, they identify a trend for API programs to be more methodical in how they plan functionality. With consumers depending upon accurate responses, you can plan the life of your API ahead of time, with the help of modern description formats.