AI Summary: OpenAPI is a language-agnostic description of an HTTP API: its paths, operations, data models, servers, and security declarations. A complete spec reduces guesswork for compatible tools, but it does not grant authorization, make unsafe operations safe, or guarantee that an AI assistant will discover or use the API.
Describe the surface, not the marketing
The OpenAPI Specification defines a language-agnostic description for HTTP APIs. Humans and tools can understand capabilities without source-code access; documentation, code generation, and testing tools can consume it. [1]
Publish a discoverable openapi.yaml or openapi.json with an explicit version. The root requires openapi and info, plus one of components, paths, or webhooks. [1] Use stable operation IDs and schemas that match actual responses.
Make operations agent-readable
For every operation, document the input location, type, constraints, authentication requirement, successful response, error responses, pagination, rate limits, and side effects. Use examples that can be replayed safely in a test environment. Separate read operations from mutations. Name a destructive operation plainly and describe whether it is idempotent, asynchronous, reversible, or subject to human confirmation.
Security declarations describe available mechanisms; they do not authorize a caller. Keep secrets out of examples and do not place credentials in query strings. Require the server to enforce scope, ownership, validation, replay protection, and rate limits even when a client has parsed the spec correctly.
| Contract area | Evidence to verify |
|---|---|
| Discovery | Public spec URL, version, server URL, and stable operation IDs |
| Inputs | Parameters and request bodies match validation behavior |
| Outputs | Success and error schemas match real response bodies |
| Security | Declared scheme, scopes, and server enforcement agree |
| Side effects | Mutation, idempotency, confirmation, and retry rules are explicit |
Verification checklist
Validate the document and references. Generate a test client and compare it with a sandbox exchange. Test invalid fields, expired credentials, insufficient scope, rate limits, duplicate mutation, and server errors; confirm no internal hosts or secrets are exposed.
An agent-ready API is not merely documented. It is a stable, testable contract whose description, runtime, and authorization behavior tell the same story.