API Development & Design — Quick Reference

Use this skill to design, implement, and document production-grade APIs (REST, GraphQL, gRPC, and tRPC). Apply it for contract design (OpenAPI), versioning/deprecation, authentication/authorization, rate limiting, pagination, error models, and developer documentation.

Modern best practices (Jan 2026): HTTP semantics and cacheability (RFC 9110), Problem Details error model (RFC 9457), OpenAPI 3.1+, contract-first + breaking-change detection, strong AuthN/Z boundaries, explicit versioning/deprecation, and operable-by-default APIs (idempotency, rate limits, observability, trace context).

Default Execution Checklist

• Choose an API style based on constraints (public vs internal, performance, client query flexibility).
• Define the contract first (OpenAPI or GraphQL schema; protobuf for gRPC).
• Define the error model (RFC 9457 + stable error codes + trace IDs).
• Define AuthN/AuthZ boundaries (scopes/roles/tenancy) and threat model.
• Define pagination/filter/sort for all list endpoints.
• Define rate limits/quotas, idempotency strategy (esp. POST), and retries/backoff guidance.
• Define observability (W3C Trace Context, request IDs, metrics, logs) and SLOs.
• Add contract tests + breaking-change checks in CI.
• Publish docs with examples + migration/deprecation policy.