15 Modifying an API

The Shopping company would like to enhance its API with support for multiple categories. Toward this end, it considers replacing the product’s category (string) with a categories array. However, that would require modifying all consuming applications’ code to use the categories array instead of the category property. A non-updated application’s code will break because the category property it expects to find isn’t there. Although updating internal applications is not a problem, asking all partners to modify their applications is more complicated. Now, imagine that such a design modification is made without anyone being informed; all the consuming applications would suddenly stop functioning. That could cost a lot of money and affect the Shopping company’s reputation.

15.1 An overview of API modification concerns

15.1.1 What can happen when modifying an API?

15.1.2 Uncovering API design modification concerns

15.1.3 How to design API modifications

15.2 Identifying breaking changes and ensuring backward compatibility

15.2.1 Modifying output data

15.2.2 Modifying input data

15.2.3 Modifying resource paths

15.2.4 Modifying operations or their HTTP methods

15.2.5 Modifying HTTP statuses

15.2.6 Modifying operation flows

15.2.7 Being aware of the invisible contract

15.2.8 Preventing unintended modifications

15.3 Identifying security-breaking changes and preventing breaches

15.4 Assigning a version to an API

15.4.1 Differentiating interface and implementation versioning

15.4.2 Choosing an API version identifier

15.4.3 How the API version can be represented in a request

15.4.4 Choosing how to represent the API version in a request

15.4.5 When to choose an API version scheme and representation

15.4.6 Avoiding sub-API-level versioning