Prefer compatible evolution within a version: add optional fields, tolerate unknown fields, and never silently change meaning. Introduce a new version only for a real breaking contract change. URL segments (/v2/orders) are explicit and cache-friendly; headers keep URLs stable but are less visible. Pick one policy and document it with OpenAPI. Keep versions side-by-side during migration, publish deprecation and sunset dates, measure client usage, and provide a migration guide. Contract tests should protect old consumers. Versioning does not replace staged database/message compatibility, and it should not encode ordinary product releases or implementation details.
Backbencher Developer · · 0 likes