Backward compatibility keeps existing API clients working while a system evolves. A seemingly helpful change can become a lasting constraint: once a classification endpoint exposed a list of labels, removing it would have broken clients, even though users needed only one label. section 13.1
Protect compatibility by:
- Designing a small external API over a more flexible internal API; internal changes then remain possible without breaking users. section 13.1.1
- Separating machine-learning logic from input/output handling so components can evolve, scale, and roll out independently. section 13.1.1
- Planning exposed fields and outputs carefully, because an unnecessary response shape can be difficult to remove later. section 13.1
- Using client libraries, feature toggles, and simultaneous component versions to make changes safer for consumers. section 13.1.1 section 13.1
Figure 13.2 Layered API structure is simpler to maintain, test, and develop.
Use the layered API diagram to distinguish the stable external contract from the changeable internal implementation. section 13.1.1
