api-design-document

## Purpose Produce an API design document that defines the complete interface contract for a new or revised API. This document is the authoritative specification that drives implementation, consumer integration, testing, and documentation simultaneously. **The cost of a bad API design is permanent.** Once consumers depend on it, changes are breaking changes. Getting the design right before the first line of implementation code is written is the highest-ROI investment in an API's lifetime. ## Input **Works best with:** The name of the API or service being designed. **Also valuable:** The domain entities and operations, consumer use cases, authentication context, existing API conventions in the codebase, performance requirements. **Example invocation:** `Design the API for a payment links system. Merchants create payment links with a custom amount, expiry, and description. Customers use the link to pay. Merchants can list, deactivate, and delete their links. Needs HMAC webhook notification on payment. Auth via Bearer token.` ## Key Concepts ### Richardson Maturity Model Target Level 2 or Level 3 (HATEOAS for discovery-driven APIs): - **Level 0:** Single endpoint, single verb - not REST - **Level 1:** Resources with unique URIs - **Level 2:** HTTP verbs and status codes used correctly - this is the minimum standard - **Level 3:** Hypermedia controls (HATEOAS) - optional, for discovery-driven APIs ### Resource Modeling - Resources are nouns, not verbs: `/payments` not `/c...