api-contracts

Think Through API & Client Contracts

Overview

Production guidance for API surfaces and their clients. Each reference paper captures the contract work that first drafts skip: request lifecycle and deadlines, validation edge cases, error taxonomies that do not leak internals, stable pagination under concurrent writes, deprecation windows, webhook signature verification, and realtime reconnection semantics.

Core principle: An API is a compatibility promise. Every endpoint, error, cursor, and webhook is a contract with real clients — including old clients you no longer control.

Domain Law

NO API OR CLIENT CONTRACT CHANGE WITHOUT:
1. the minimum required primary paper(s) for the surface selected from the context table;
2. the paper's pre-change questions
   answered, or each open point labeled as an assumption;
3. "Existing-codebase checks" run when changing an existing API;
4. every applicable MUST mapped to a decision, a test, or a documented
   exception — never silently downgraded.

When to Use

Use this skill when thinking through, reviewing, changing, or verifying:

• REST, RPC, gRPC, or GraphQL endpoints and resource/command design;
• request parsing, body limits, content-type handling, and input validation;
• error architecture: codes, HTTP status mapping, public vs internal detail;
• pagination (offset/cursor), filtering, sorting, and query complexity limits;
• bulk and batch operations with partial-failure reporting;
• API versioning, deprecation, sunset windows, and breaking-change detection;
• data serialization choices and precision/compatibility pitfalls;
• webhooks: registration, signing, timestamp/replay validation, retries, dead-lettering;
• realtime communication: WebSockets/SSE, presence, reconnection, ordering;
• SDK/client libraries and CLI-backend interactions;
• security headers for browser-facing APIs.

When Not to Use

• Whole-system architecture design: use system-architecture-harness.
• Authentication, authorization, API keys: use auth-access.
• Queue delivery semantics, events, outbox: use async-messaging.
• Database schema evolution sequencing: use migration-evolution (070 overlaps at the contract level).
• Rate limiting and quotas mechanics: use resilience-flow-control (038, 039).