Backward compatibility lets an API change while existing consumers continue working with the data, operations, flows, and expectations they already rely on. It protects end users from crashes, confusing errors, silent behavior changes, and corrupted outcomes. section 1.2.4 section 15.2
Evolving a Shopping API
Replacing a product's category string with a categories array breaks applications that still read category. A compatible alternative keeps category and adds a new optional field. Similarly, replacing a numeric price with a value-and-currency object can be avoided by retaining price and adding priceCurrency with a default value. Existing consumers continue working while updated consumers adopt the richer representation. section 15.0 section 15.1.1
Use these boundaries when modifying an API:
- For output data, add fields, retain expected fields and types, and modify values only within their original limits. Do not rename, remove, newly require, or unexpectedly retype consumer-visible data. section 15.2.1
- For input data, make required data optional, add optional data, or expand existing limits. Preserve accepted values and meanings so old requests cannot trigger errors or harmful reinterpretations. section 15.2.2
- Check headers, paths, operations, statuses, flows, and security schemes as well as bodies; version the interface contract when a breaking change cannot be avoided. section 15.2 section 15.8
Figure 15.3 Breaking changes can occur in headers and bodies of any success or error response. Only add or modify data within the limits of the original data to be backward compatible.
Use the compatibility boundary as a quick review rule: add or adjust response data only within the original data limits. section 15.2.1
