API Industry Guide: API Definitions
24 Sep 2019
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.
This guide is meant to help decision makers make sense of how the API movement grew organically out of the Service Oriented Architecture (SOA) industry and produced a wealth of competing schema and API definition formats that are used to define what APIs do, but also are critical for powering almost every stop along the API lifecycle. While this guide is focused on a very technical subject, it is designed to be consume by both developers and non-technical audiences, attempting to encourage business and technical stakeholders to work together to deliver the next generation of providers.
API definitions aren't just the first stop in the API lifecycle. They are the most critical stop that will service every other stop, providing the human and machine readable definitions that are needed to deliver the technology and business of APIs. Get your copy of the API Evangelist API Definitions Industry Guide to help give you the understanding you need of why API definitons are critical to your API success. Helping ensure you have all of your organization'ss capabilities properly defined, discoverable, and properly applied across teams for all of the APIs you are delivering or consuming.