api-designlisted

# API Design Build interfaces that are hard to misuse. Design from the consumer's perspective. ## Progress Checklist - [ ] Determine context (internal vs public) - [ ] Define contract first (OpenAPI/types) - [ ] Design from consumer perspective - [ ] Validate at boundaries - [ ] Consistent error responses - [ ] Sane defaults - [ ] Generate types from spec ## Step 0: Context Check This changes everything about the design: | Question | Internal API | Public API | |----------|-------------|-----------| | Who consumes it? | Your team, known services | Unknown third parties | | Breaking changes? | Coordinate and deploy together | Version, deprecate, migrate | | Auth complexity? | Service-to-service tokens | OAuth, API keys, rate limiting | | Documentation? | Enough for the team | Comprehensive, with examples | | Backward compat? | Just change it | Required, additive only | Don't apply public-API rigor to an internal endpoint you own both sides of. ## Step 1: Contract First Define the interface before writing implementation: - Write an OpenAPI/Swagger spec, or - Define TypeScript types for request/response, or - Define the protobuf/gRPC schema This forces you to think about the shape of data before getting lost in business logic. ## Step 2: Consumer-Driven Design Write the calling code first (or imagine writing it). Ask: - Is this intuitive to call? - Are there too many required parameters? - Are defaults sane? (Do I have to pass 10 options to do the common thing?) -