Openapi Glossary

OpenAPI Glossary

Source: https://github.com/apisyouwonthate/api-glossary

To avoid confusion in the creation of educational material, tooling, and other content, having a shared vocabulary is important. A lot of people in the OpenAPI community call a lot of things a lot of different things, so let's take a swing at unification here.

API

The general definition "Application Program Interface" can mean a lot of things, with different types of interface. OpenAPI is specifically talking about HTTP-based APIs, which in general is anything REST, RESTish, and many generic types of RPC.

API-First

When APIs first started getting popular, a lot of companies started flopping them out as a marketing ploy. These APIs were generally not particularly useful, rarely performant, and frustrating to work with.

"API First" is a concept that teams should build the APIs first, and make them something they would want to work with, therefore solving useability issues, performance issues, etc. and supposedly creating a better experience for their customers.

API Description

Aliases include: "API Definition" or "API Contract".

An API Description is meta-data about an API, explaining what endpoints, resources, HTTP methods, headers, query parameters, etc. exist.

Descriptions are written in a particular "API Description Format" (e.g.: OpenAPI, JSON Schema, RAML, WSDL, etc.) and will usually be contained in an "API Description Document" (e.g.: openapi.yaml, schemas/payment.json) unless the authors decided to use annotations instead.

API Design

Planning an API specifically using API Descriptions, or a tool which generates / exports API descriptions. When done before coding begins, it is known as API Design First, which is conceptually different to API First but not mutually exclusive.

More on API Design First vs Code First.

API Specification

In the past the term API Specification was one of many terms to describe what most major tooling vendors call an API Description Document. It was the file that users would write to describe their API.

Ask 100 people and you will get 100 answers, but consensus is forming around API Specifications being an umbrella term for various Specifications involved with API development, and more specific categories exist within the umbrella term.

Message Formats like JSON-API, HAL, Siren, etc. all have a specification. Data Formats like JSON, YAML, etc all have a specification. Transfer Protocols like SPDY, HTTP/2, HTTP/3, etc have a specification. Authentication Strategies like OAuth 2, OpenID, etc all have a specification.

Seeing as there as so many types of API specification floating around, to disambiguate its best to just avoid the term and use one of the more specific categories, or if talking about your own openapi.yaml just call it the description document.

Bundle

Aliases include: "External Inlining".

Bundling pulls in external $refs from different files, or URLs, and puts them into the components object.

This is done to create a single OpenAPI file, which is easier to share, especially with tooling that does not support resolving external files. If tooling does not support $ref at all, then an alternative to bundling is required: dereferencing.

Callbacks

Most programming languages have a concept of a callback which is a function passed as an argument to another function, which is run after another function has finished. The exact same concept exists in APIs, where a URL can be passed to be alerted when an action is complete.

This is usually performed via a Webhook, so the term Webhook would be more common than Callabck, but OpenAPI specifically talks about Callbacks.

For example, your API provides a POST /subscribe operation that expects a callback URL in the request body:

POST /subscribe
Host: my.example.com
Content-Type: application/json
{
  "callbackUrl": "https://myserver.com/send/callback/here"
}

A Webhook will then be sent to that URL.

More about OpenAPI callbacks on Swagger Docs: Callbacks.

Code Generation

Contract Testing

Confirming that an API is accepting and outputting what it says it is can take many forms. Most commonly, when you hear the term Contract Testing in relation to OpenAPI, people are talking about producer contract testing. This means the API development team (or some test/QA team nearby) have implemented a test suite that will take an API description and compare it to the actual data.

Conceptually contract testing is the same thing as data validation, but done for different purposes at different parts of the life-cycle. The same tools could be used under the hood.

There is also client-side contract testing, where you write out the contract in a client test suite then make calls to the API to see if it matches.

Converter

A set of tools that allow you to convert OpenAPI descriptions to another description format, such as API Blueprint, HAR, RAML, etc., or vice versa! Some will also convert to HTML which is usually for making reference documentation.

Data Instance

Data Validation

Often referred to simple as "validation" when there are many types of validation. Data validation is basically taking some real data (maybe an entire HTTP Message with a body, or just the body) and comparing it to the API description.

This is then used to power things like contract testing, gateway validation, and server-side validation.

Dereference

Aliases include: "Dereferencing", "Internal Inlining" or "Transclusion".

All $refs and replaced with their values à la copy & paste. No more $ref's exist in the file/object representation. If you have 10 operations referencing the same model 10 times, you now have 10 different models.

Description Validation

Aliases include: "Schema Validation".

A very different type of validation to data validation. Description validation focuses on making sure the description is correct against the OpenAPI Specification itself.

When a validator moves beyond checking the document is valid, and into custom rules, design opinions, style, etc. the term "linting" is used.

A list of description validators is available on OpenAPI.Tools.

Documentation

The most common meaning of documentation in OpenAPI-world is reference documentation, but there is a lot more to good API documentation than just that. Guides, tutorials, and other types of how-to content is often combined with reference documentation to provide the best developer experience. This combination along with "sign up for API tokens" type functionality is often referred to as a Developer Portal.

Gateway Validation

Data Validation leverages in an API Gateway is known as gateway validation, and it will stop invalid requests from wasting application resources. AWS, Tyk, Express Gateway, etc. support some level of OpenAPI or JSON Schema gateway validation.