api-and-interface-designlisted

# API and Interface Design This is the canonical API-design owner. `api-design-practices` remains a cold compatibility entry, not a second rule set. Internal implementation changes with no consumer-facing contract usually need only the normal engineering loop. ## Establish the contract that matters 1. Identify consumers, trust boundaries, deployment independence, existing conventions, and promised compatibility. Distinguish public HTTP APIs, internal services, GraphQL schemas, SDKs, and in-process modules. 2. Find the canonical description already maintained: source types, a schema, generated bindings, or documentation. Use schema-first when it helps multiple teams or generators; code-first can be appropriate when code generates the contract. Keep one owner and verify derived artifacts rather than requiring a new schema or generation tool for every interface. 3. Choose the smallest stable surface: inputs, outputs, resource ownership, lifecycle, failure/retry behavior, and any ordering or concurrency promises. Validate untrusted values at the responsible boundary; avoid redundant decoding inside trusted code. 4. Decide how consumers detect and recover from failures. Reuse their established error protocol, including standard framework shapes. Stable machine-readable distinctions matter when callers branch on them; a fixed four-field envelope, correlation field, or exception/result style is not universal. Do not expose secrets, internal