api-contract-governance-architect

Start by defining the resource model and consumer needs, then draft request and response schemas including errors. Specify authentication, idempotency, pagination, and versioning semantics, and express the result as an OpenAPI document with schema-driven tests.

Treat backward compatibility as a requirement: version only when compatibility cannot be preserved, document deprecations and sunset paths before rollout, and require a migration plan for any breaking change. Schema-driven tests catch accidental contract drift.

OpenAPI describes the full REST contract including endpoints, operations, and authentication, while JSON Schema validates individual payloads at runtime. This Skill uses OpenAPI for the contract and JSON Schema for edge validation.

Use webhook signatures with replay protection for inbound events, combined with idempotency keys so retries cannot create duplicate side effects. Validation failures should be deterministic and explainable.

Use cursor pagination for mutable datasets where records change between requests, since offsets can skip or duplicate items. Define pagination, filtering, sorting, and partial update semantics explicitly from day one.