api-contract-evolution
Installation
SKILL.md
API Contract Evolution
Change APIs without breaking clients you can't force-upgrade. design-api covers writing new endpoints; this covers changing them over time.
Versioning Strategy — Choose One
| Strategy | Use when |
|---|---|
URL path (/v1/, /v2/) |
Public APIs, mobile clients — visible, cacheable, easy to test. Preferred. |
Header (API-Version: 2024-01-01) |
Internal service-to-service where all callers are under your control. |
Query param (?version=2) |
Avoid — breaks caching and is easy to forget. |
| GraphQL field evolution | Add fields, @deprecated, remove only after confirmed zero usage. |
Breaking vs Non-Breaking
Non-breaking (safe without a version bump)
- Add optional request fields with sensible defaults.
- Add response fields (test that clients actually ignore unknown fields).
- Relax validation; add new endpoints or enum values.