Skip to content

OpenAPI Glossary

This glossary defines terms related to APIs, REST, and the OpenAPI Specification.

API

pronunciation

  • /ˌeɪ.piːˈaɪ/ ("ay-pee-eye")
  • Pronounced as individual letters A-P-I, not as a word

noun

  • application programming interface (API)
  • I used the GitHub API to query my repositories.
  • APIs are used to interact with software applications.
  • I wrote an SDK for the Stripe API.
  • This JavaScript module's API is well-designed.

Note: The abbreviation is common enough that it's most often used without explanation

  • We don't need to spell out "application programming interface" before mentioning APIs.
  • If someone doesn't know that API refers to "application programming interface", they probably need the unabbreviated term explained anyway.

REST

pronunciation

  • /rɛst/ ("rest")
  • Pronounced like the word "rest"

noun

  • representational state transfer (REST)
  • REST is a specific software architectural style.
  • RESTful APIs are based on the principles of REST.
  • REST is a popular design choice for web services (APIs that work over the web via HTTP).

RESTful

pronunciation

  • /ˈrɛstfʊl/ ("REST-full")
  • Pronounced like the word "restful", with emphasis on "REST"

adjective

  • (of an API) conforming to the principles of REST
  • RESTful describes an API that follows REST principles.
  • RESTful APIs are easy to use and understand.
  • Our API is RESTful because we followed the principles of REST when we designed it.

REST API

noun

Note: Most often used to distinguish from APIs that follow other principles

Swagger API

proper noun

  • The Swagger API project
  • Swagger API was an open-source project that developed tools for designing, building, and documenting APIs.
  • The Swagger API project was created in 2011 by Tony Tam but belonged to Reverb Technologies.
  • The Swagger API project developed the original Swagger Specification.
  • In 2015, SmartBear acquired the Swagger API project from Reverb Technologies.
  • In 2016, SmartBear granted only the Swagger Specification to the OpenAPI Initiative.

OpenAPI Specification

proper noun

Note: The OpenAPI Specification is the successor to the Swagger Specification

Note: The OpenAPI Specification is sometimes referred to as OAS

  • The OpenAPI Specification is sometimes referred to as OAS by industry insiders.
  • We rarely use the abbreviation when writing for a general audience or even for most technical audiences.

Note: There are multiple versions of the OpenAPI Specification

  • The OpenAPI Specification has multiple versions, with the latest (as of October 2024) being 3.1.0.
  • When referring to a specific version, include the version number, such as "OpenAPI Specification 3.1.0" or "OAS 3.1.0."
  • When referring to multiple versions collectively, use "OpenAPI Specification Versions", or (rarely) the plural "OpenAPI Specifications".
  • The singular form "OpenAPI Specification" usually refers to the latest version of the specification.

common forms

  • ✅ OpenAPI Specification
  • ❌ OpenAPI Spec (ambiguous)
  • ❌ OpenAPI Definition (ambiguous)
  • ❌ OpenAPI Schema (ambiguous)
  • ❌ OpenAPI File (ambiguous)
  • ❌ OpenAPI Spec (ambiguous)
  • ❌ Swagger Specification (deprecated)
  • ❌ Swagger Spec (deprecated)
  • ❌ Swagger Definition (deprecated)
  • ❌ Swagger Schema (deprecated)

OAS

pronunciation

  • /oʊ.eɪ.ɛs/ ("oh-ay-ess")
  • Pronounced as individual letters O-A-S, not as a word

abbreviation

Note: The OpenAPI Specification is sometimes referred to as OAS

  • We rarely use the abbreviation when writing for a general audience or even for most technical audiences.

OpenAPI document

noun

common forms

  • ✅ OpenAPI document
  • ⚠️ OpenAPI file (ambiguous)
  • ⚠️ OpenAPI schema (ambiguous)
  • ❌ OpenAPI spec (ambiguous)
  • ❌ OpenAPI definition (ambiguous)
  • ❌ Swagger specification (deprecated)
  • ❌ Swagger document (deprecated)
  • ❌ Swagger file (deprecated)
  • ❌ Swagger schema (deprecated)
  • ❌ Swagger spec (deprecated)
  • ❌ Swagger definition (deprecated)

OpenAPI Initiative

proper noun

Note: The OpenAPI Initiative is sometimes referred to as OAI

Arazzo Specification

pronunciation

  • /əˈrɑːzoʊ/ ("uh-RAH-zoh")
  • Pronounced like "uh-RAH-zoh", with emphasis on the second syllable

proper noun

  • A specification for designing or describing API workflows
  • The Arazzo Specification is a standard for describing workflows, or sequences of API calls, as Arazzo documents.
  • The Arazzo Specification is maintained by the OpenAPI Initiative.
  • The Arazzo Specification is designed to reference objects defined in OpenAPI documents.

Note: Arazzo means "tapestry" in Italian

  • The name Arazzo was chosen to evoke the idea of weaving together multiple API calls into a single workflow.

common forms

  • ✅ Arazzo Specification
  • ❌ Arazzo Spec (ambiguous)
  • ❌ Arazzo Definition (ambiguous)
  • ❌ Arazzo Schema (ambiguous)
  • ❌ OpenAPI Workflows Specification (deprecated)
  • ❌ OpenAPI Workflows (deprecated)

Arazzo document

noun

  • A document that conforms to the Arazzo Specification
  • An Arazzo document is a JSON or YAML file that describes a workflow according to the Arazzo Specification.
  • Arazzo documents are used to generate workflow documentation and test suites.
  • Arazzo documents conform to JSON Schema.

common forms

  • ✅ Arazzo document
  • ⚠️ Arazzo file (ambiguous)
  • ⚠️ Arazzo schema (ambiguous)
  • ⚠️ Arazzo spec (ambiguous)
  • ⚠️ Arazzo definition (ambiguous)
  • ❌ Arazzo workflow (ambiguous - refers to a concept rather than a document)
  • ❌ OpenAPI workflow (deprecated)

JSON Schema

proper noun

  • A vocabulary that allows you to annotate and validate JSON documents
  • JSON Schema is a specification for defining the structure of JSON data.

Note: Capitalization is important to distinguish the specification from instances

JSON schema

noun

  • A schema document or JSON object that conforms to the JSON Schema specification
  • I wrote a JSON schema to validate our API responses.
  • The JSON schema defines the expected structure of our data.

Note: Lowercase "schema" indicates an instance, not the specification

YAML

pronunciation

  • /ˈjæməl/ ("YAM-ul")
  • Rhymes with "camel", not pronounced as individual letters

noun

  • YAML Ain't Markup Language (recursive acronym)
  • A human-friendly data serialization language
  • YAML is often used to write OpenAPI documents because it's more readable than JSON.
  • Many developers prefer YAML over JSON for configuration files.

JSON

pronunciation

  • /ˈdʒeɪsən/ ("JAY-sun")
  • Pronounced like the name "Jason", not as individual letters

noun

  • JavaScript Object Notation (JSON)
  • JSON is a lightweight data interchange format.
  • JSON is easy for humans to read and write and easy for machines to parse and generate.
  • JSON is a common data format with diverse applications.
  • JSON is used for serializing and transmitting structured data over a network connection.
  • JSON is a popular alternative to XML for APIs.

Swagger

proper noun

Note: Often confused with OpenAPI Specification, OpenAPI Initiative, Swagger API, and Swagger Specification

Swagger UI

proper noun

Swagger Editor

proper noun