An API contract is more than a list of endpoint URLs. Consumers need to know how to authenticate, which fields are required, how errors are represented, whether requests can be retried and how pagination behaves.
Document request and response shapes
For each endpoint, define the HTTP method, path parameters, query parameters, headers, request body and response schema. Distinguish missing, null and empty values. Include examples that are valid but do not contain real credentials or personal data.
Define authentication and authorization
Explain the authentication mechanism and required scopes or roles. Document which resources the caller may access and how permission failures are returned. Do not expose internal authorization rules that would create unnecessary security risk.
Standardize errors
Use stable machine-readable error codes and a predictable response structure. Include validation, authentication, authorization, not-found, conflict and rate-limit cases. Human-readable messages can change, but clients should not need to parse prose to determine what happened.
Explain retry and pagination behavior
Document rate limits, retry guidance, idempotency expectations and cursor or offset semantics. Tell consumers whether list results have stable ordering and whether a cursor can expire.
Checklist
- Document every input and output field.
- Include authentication and authorization behavior.
- Define stable error codes and response shapes.
- Explain pagination, rate limits and retry rules.
- Provide safe, realistic request examples.