Backward compatibility means that code written for an earlier web API version continues to communicate and function as expected after the server changes. Because clients are outside the API designer’s control, compatibility is judged primarily by whether existing client code survives the replacement. section 24.2.1 section 24.6
Traffic shift from v1 to v1.1
Suppose client code currently calls API v1. Shift its traffic to v1.1 without changing the client. If the client continues functioning, the two server versions are compatible. The test becomes harder when behavior changes without altering the request shape: fixing floating-point addition can change returned values, while delaying message delivery can break code that expects immediate sequencing. section 24.2.1 section 24.2.2
Compatibility is not determined solely by signatures or by the designer’s intention. A change is breaking when it violates an expectation that existing users could reasonably rely on. Even a bug fix or a change from hard deletion to soft deletion may therefore require compatibility review. section 24.2.2 section 24.6 section 25.3.8
Apply a deliberate compatibility policy:
- Define which user-visible behavior counts as supported before classifying changes. section 24.2.2
- Balance stability against new features, bug fixes, security patches, and infrastructure changes instead of deciding ad hoc. section 24.4.2
- Avoid treating every change as a separate version when excessive granularity overwhelms users and couples them to an entire historical release. section 24.4.1
- Treat soft deletion conservatively: examine expiration, data purpose, privacy, security, and regulations, and consider a major-version increment when compatibility is uncertain. section 25.3.8
Use the compatibility experiment to reason about whether existing client traffic can move from one API server version to another without client changes. section 24.2.1
