api-contract-governance-architect

Start by defining the resource model and consumer needs, then draft request and response schemas including errors before implementation. Specify authentication, idempotency, and pagination semantics, and document the result as an OpenAPI contract that consumers can generate clients from.

Treat backward compatibility as a requirement: never emit undocumented fields, version only when compatibility cannot be preserved, and document deprecations and sunset paths before rollout. Schema-driven tests catch accidental contract drift before release.

Use stable error envelopes containing machine-readable codes, human-readable messages, and field-level detail. Validation failures should be deterministic and explainable so consumers can handle them programmatically.

Use cursor pagination for mutable datasets where records change between requests, since offset pagination can skip or duplicate items. Define pagination, filtering, and sorting rules explicitly in the contract from day one.

Define idempotency semantics explicitly so retries cannot create duplicate side effects, typically via idempotency keys on mutating endpoints. For inbound webhooks, add signatures and replay protection to reject duplicate or forged events.