agent-api-contract-designer

Write the OpenAPI contract before implementation with strict typed schemas, enums, and idempotency keys on all mutating endpoints. Target Richardson maturity level 2 so agents can infer retry-safety from HTTP verbs and status codes, and publish a machine-readable error taxonomy with retryability classes.

Allow only expansion changes within a major version: add endpoints, optional fields, and enum values, but never rename, remove, or retype. Semver the contract, run majors side by side with deprecation windows and sunset headers, and document tolerant-reader obligations for consumers.

OAuth2 client credentials are preferred for machine-to-machine calls because they are scoped, short-lived, and attributable. Static API keys are unscoped, unexpiring, and unattributable, acceptable only for low-risk read-only telemetry at most.

Consumer-driven contracts are executable expectations each consumer class contributes describing the fields and behaviors it relies on. The provider's CI runs all of them on every change, turning potential breaking changes into build failures rather than review-time guesses.

Agents may be prompt-injected, running compromised models, or fed poisoned context, so their requests are attacker input with valid credentials. The skill applies STRIDE-per-element over the data-flow diagram plus a seven-point checklist covering server-side revalidation, TOCTOU, non-leaking errors, and per-identity quotas.

Create a BFF per consumer class when different consumers genuinely need different payloads, scopes, and rate limits, such as an experiment-runner agent versus a human portal. Each BFF trims payloads to that class's needs and versions independently, but avoid multiplying BFFs beyond real consumer classes.