Specification

A specification in the API world is a formal, machine-readable description of how an API behaves — its endpoints, operations, request and response schemas, authentication, and errors — captured in a document that both people and tooling can read. Rather than describing an API in prose, a specification turns the contract into structured data that can drive documentation, mock servers, SDK generation, testing, and governance from one source of truth.

• A single source of truth - One artifact the whole lifecycle references, so design, docs, and code stay aligned instead of drifting apart.
• Machine-readable contract - Structured enough that tooling can validate, mock, and generate against it without a human in the loop.
• A family, not one format - OpenAPI, AsyncAPI, JSON Schema, and Arazzo each specify different facets of API behavior.
• Governable - Because it is data, a specification can be linted and enforced with tools like Spectral.

Specifications are the backbone of how I evaluate and score APIs, because an accurate spec is what makes an API discoverable, testable, and reusable rather than a black box. As I have written, the landscape is fragmented and politically fraught, and specs rot when they drift from the running API — but that same machine-readable contract is exactly what the agentic turn depends on, since an AI agent needs a precise description of an API before it can safely call it.