API Definition

Overview

Meaning and scope

API Definition is the formal description of an API’s available operations, data models, parameters, responses, security, and protocol details. It is used to provide a shared representation that tools and teams can use to implement and govern the interface. It differs from an API contract, which also includes behavioral promises and organizational obligations beyond the formal description.

Mechanism and operation

The definition is authored in OpenAPI, AsyncAPI, protocol buffers, GraphQL schema language, or another format and published with the service version. Testing API Definition should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes. Important failure modes include missing operations, undocumented extensions, inconsistent examples, and divergence from runtime behavior. The API Definition contract should define identifiers, validation, authorization, status semantics, errors, limits, and version behavior at the same boundary. Operational evidence should include definition format, revision, service version, validation result, generated artifact versions, and owner.

Practical payment example

A development team publishes an OpenAPI specification so a test runner can validate endpoints, parameters and response types.

Operational checks

API Definition should be documented alongside API Contract, API Schema, and OpenAPI Specification. Changes to API Definition should be checked against older clients, stored payloads, enum growth, default behavior, and retry assumptions. The API Definition owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate.

Distinctions and limits

Treat it as source-controlled code, validate it, generate artifacts reproducibly, review changes, and compare against deployed behavior. Data handled by API Definition should use documented types, units, timestamp rules, nullable fields, and enum behavior to prevent silent interpretation errors.

Related reading

Related definitions: API Contract, API Schema.