9 Evolving an API design


This chapter covers

  • Designing evolutions to avoid breaking changes
  • Versioning APIs to manage breaking changes
  • Designing extensible APIs to limit breaking changes

In the previous chapters, you learned how to design APIs that provide features or goals that make sense for their users. You also learned how to design user-friendly and secure representations of these goals. Once all that work is done, is that the end of the API designer’s job? Not at all! It’s a new beginning.

An API is a living thing that will inevitably evolve, perhaps to provide new features or enhancements to existing ones. To design for such evolutions, you can reuse the same skills you have learned up to this point—but designing evolutions requires some extra care.

9.1 Designing API evolutions

9.1.1 Avoiding breaking changes in output data

9.1.2 Avoiding breaking changes to input data and parameters

9.1.3 Avoiding breaking changes in success and error feedback

9.1.4 Avoiding breaking changes to goals and flows

9.1.5 Avoiding security breaches and breaking changes

9.1.6 Being aware of the invisible interface contract

9.1.7 Introducing a breaking change is not always a problem

9.2 Versioning an API

9.2.1 Contrasting API and implementation versioning

9.2.2 Choosing an API versioning representation from the consumer’s perspective

9.2.3 Choosing API versioning granularity

9.2.4 Understanding the impact of API versioning beyond design

9.3 Designing APIs with extensibility in mind

9.3.1 Designing extensible data

9.3.2 Designing extensible interactions

9.3.3 Designing extensible flows

9.3.4 Designing extensible APIs