An API Evangelist Industry Guide: API Definitions

This is a guide to the world of API definitions. Introducing you to what the machine and human readable schema and API specification formats are used for when it comes to defining API-driven capabilities. Formats like JSON Schema, OpenAPI, AsyncAPI, and Postman Collections are changing how we define our APIs, and then use definitions to engage with developers throughout the API life cycle.

This API definitions guide is the result of almost 10 years of research and participation in the evolution of API definitions as part of community development, conferences, and the API efforts behind the specifications themselves. I've worked to distill my research on API definitions down into a short guide that business as well as technical individuals can follow. Providing a single guide to the impact that API definitions are making across the sector, empowering both API providers and consumers when it comes to putting APIs to work in web, mobile, and device applications.

Table of Contents:

- API Definitions - Overview of what API definitions mean to stakeholders.

- Defining APIs - How API definitions are used to define each individual API.

- Machine Readable - Providing what is needed for systems to understand.

- Human Readable - Providing what is needed for humans to understand.

- JSON Schema - A standard for describing the properties of each API object.

- OpenAPI - Standard for defining API contracts for HTTP 1.1 or web APIs.

- AsyncAPI - Standard for defining API contracts for Kafka, AMQP and other APIs.

- Postman - An executable format for defining and interacting with APIs.

- APIs.json - An open standard for defining the operations that surround an API.

- Tagging - Using tags to label and organize API definitions across API operations.

- Versioning - Using semantic versioning to properly evolve API definitions used.

- Extending - Understanding that you can extend API definition formats to meet needs.

- Life Cycle - API definitions are used across multiple stops of a modern API life cycle.

- Tooling - Tools that can be used to reduce friction when managing API definitions.

- Defining Operations - API definitions define APIs, as well as API operations.

- Defining Consistently - API definitions help consistently deliver APIs for consumers.

- Reusing Patterns - Reuse of patterns across APIs are enabled using API definitions.

- Defining Capabilities - API definitions are about defining the capabilities APIs enable.

- Providing API Contracts - API definitions have the potential to act as API contracts.