Bringing law and order to APIs with OpenAPI Specifications
By: Joyce Lin
Tags: Development, API, Programming, Software Development, Code

Schemas — this is how data looks

Schemas include metadata referring to your data models and provide information about the resource representations that your API accepts or returns. For example, JSON Schema is a specification declaring the proper structure of JavaScript Object Notation (JSON) data used frequently with web APIs, and is used to validate the correct format for the body of a request or response.

API description formats — this is a way to describe APIs

These formats are sometimes called API specification formats, and are usually based on a specification format (such as OpenAPI Specification) that combines a schema language (such as JSON Schema) and other information to describe endpoints, headers, and all the stuff that’s not in the body (that’s covered in a schema).

API description document — this is how a particular API works

These documents are sometimes called API specifications, and is a file that contains all the stuff from your description format fleshed out with information related to your actual API. This file describes how the API works. It can be used as a contract to programmatically build workflows useful for API development, such as tests or documentation.

API documentation — this is how to use a particular API

Documentation talks about how to use an API, and will typically include a technical reference as well as functional guides for how to interact with the API across various use cases. An API consumer who reads the API documentation should understand how to use the API.

There are meaningful differences between all of these concepts. But once again, experts don’t always agree on these meanings, and they’re frequently referred to interchangeably or ambiguously. For example, when someone says “API specification”, they could be referring to either the format for describing APIs, the file intended to drive API development, or the file generated to document an API.

The important thing is to understand these basic concepts, and then determine what is helpful for your organization’s desired workflow.

If your head hurts from reading this, so does mine. Let’s forge ahead and walk through a couple examples.

Example #1: Building blocks

From the building blocks of modern software to the building blocks of life — let’s talk about APIs and DNA.

DNA is the blueprint for every living organism

In biochemistry, DNA is the blueprint for every living organism. A schema establishes the rules for how biological molecules pair together to form chemical strands of a double helix 🧬

The human genome is a description format offering a complete genetic blueprint for building human beings. This mapping provides detailed information about the structure, organization, and function of the complete set of human genes.

My personal DNA sequence can be captured in a description file. My DNA follows the general rules of DNA, particularly that of a human’s DNA, and not an alligator or mushroom 🐊🍄

My documentation helps others understand how to interact with me. I must be fed 4–5 times a day, and I’ll get grumpy if you talk to me while I’m busy working with my headphones on.

Let’s walk through one more example — this time with our friendly, neighborhood Postman.

Example #2: Postman collections to describe an API