A non-breaking API change preserves the contract existing clients rely on, so they can continue operating without coordinated upgrades. In microservices, favor compatible changes to reduce deployment dependencies. section 7.5.2 section 8.1.5
Apply compatibility deliberately:
- Add optional request attributes or response attributes; old clients can ignore a new response property. section 7.5.2 section 8.1.5
- Use Semantic Versioning as a guide: increment MINOR for backward-compatible enhancements and PATCH for backward-compatible bug fixes. section 8.1.5
When a change must break compatibility
Run old and new API versions side by side, migrate clients, then remove the old version. REST APIs can use versioned URL paths such as /v1/ and /v2/. section 7.5.2 section 8.1.5
