An API modification changes an existing interface or its observable contract after consumers already depend on it. Treat every change as an API design problem: preserve backward compatibility where possible, or knowingly manage the consequences when breaking change is necessary. Poorly planned changes can break consumer code, damage user interfaces, corrupt data, or create security problems. section 1.3.2 section 15.0
Design an API modification through these practical checks:
- Identify the new or corrected user need and design the matching capability as usual. section 15.1.3
- List every modification exhaustively, including affected operations, schemas, consumers, security behavior, and documentation. section 15.1.2
- Determine whether each change is backward compatible and assess its value against migration cost and consumer impact. section 15.1.2
- Choose a migration strategy: revise the design to preserve compatibility, synchronize known deployments, or expose versions in parallel. section 15.1.1
- Update the API description, version number, and change log, while communicating required consumer updates. section 15.1.3
Changing product prices
Replacing a numeric price with an object containing value and currency makes existing consumers fail when reading products and makes old requests invalid. A compatible alternative keeps price unchanged and adds priceCurrency with a default value. If the richer representation is essential, parallel API versions let partners migrate at their own pace. section 15.1.1
Schema change exercise
Compare the before-and-after schemas for GET /machine-reports/{reportId}. Identify changes to required fields, property names, identifier patterns, date formats, nested condition data, temperature units, and the added pressure field; then judge compatibility. section 15.12
Figure 15.1 Modifying a consumed API is “design as usual,” with the constraint of determining how modifications will affect consumers and making trade-offs if necessary. The initial design can facilitate later modifications.
Use the figure to frame modification as ordinary API design plus explicit analysis of consumer effects and trade-offs. section 15.1
