api-contract-designlisted

# API Contract Design Most API problems that look like "the frontend and backend disagree" are actually a contract that was never made explicit, and both sides guessed compatibly for a while until they didn't. This skill makes the contract explicit before code on either side depends on an assumption. ## Step 1 — Choose the protocol by requirement, not habit - **REST** — resource-oriented access with good cacheability, when the access pattern maps cleanly to a fixed set of resources and standard HTTP semantics fit. - **GraphQL** — when clients genuinely need flexible, partial data shapes and over-fetching/under-fetching with a fixed REST shape is a real, current problem — not by default because it's more flexible in theory. - **gRPC** — for internal service-to-service calls where performance, strong typing, and/or streaming matter more than human-readability or broad client compatibility. State the actual reason for the choice — "REST because that's what we always use" is not a decision, it's an unexamined default. ## Step 2 — Decide versioning strategy up front URI versioning, header versioning, or schema evolution via additive-only changes — pick one and state the deprecation policy alongside it: how long old versions stay supported, and how consumers are notified before a version is retired. A versioning strategy decided after the first breaking change is needed is a strategy decided too late. ## Step 3 — Design the error contract as a first-class part of the API A c