api-and-interface-designlisted

# API and Interface Design Contract-first design for HTTP APIs, GraphQL, CLI surfaces, and library module boundaries. Complements `secure-api-design` (security) and `agent-tool-contracts` (LLM tools) with general interface ergonomics and evolution rules. ## When to use - New public or cross-team API - Breaking-change review - Designing pagination, filtering, idempotency, or error shapes ## When not to use - Internal refactor with no boundary change - Security-only audit (use `secure-api-design`) - Agent tool schema only (use `agent-tool-contracts`) ## Design checklist ### Contract - Resource naming consistent (nouns, plural collections) - Versioning strategy documented (URL prefix, header, or additive-only) - Request/response schemas with examples for happy path + common errors - Idempotency keys for mutating operations where retries matter ### Errors - Stable machine-readable codes separate from human messages - HTTP/status mapping documented; no stack traces in client responses - Validation errors: field-level detail when safe (no PII leakage) ### Pagination and lists - Cursor-based preferred for large/live datasets; offset only when bounded - Default and max page size documented - Sort/filter params explicit; reject unknown params predictably ### Compatibility - Additive changes only in minor versions - Deprecation headers or sunset dates for removals - Consumer migration notes in changelog ### Observability - Correlation/request IDs in responses or logs -