API Versioning with Claude Code: Evolving APIs Without Breaking Clients

Every API change risks breaking existing clients. Versioning strategy, designed upfront, lets you evolve the API safely. Claude Code generates the complete versioning infrastructure when you define the rules. CLAUDE.md for API Versioning ## API Versioning Rules ### Versioning approach - URL path versioning: /api/v1/users, /api/v2/users (Simple, cacheable, easy to debug) - Header versioning: not used ### Version management - New version: add new files, never modify existing version - Deprecation: notify via Deprecation-Date header (6 months before sunset) - Removal: minimum 6 months deprecation notice required ### Backward compatibility (within same version) - Never remove fields (make optional first, then remove in next version) - Never rename fields (add new name, deprecate old one) - Never change field types (string → number is breaking) - Additions are OK (new fields, new endpoints) ### Support lifecycle - Current: full support - Previous: 12 months (bug fixes only) - Older: unsuppo