Skip to content

API Evolution

Every change to an existing, published API MUST avoid breaking changes and SHOULD maintain backward compatibility.

The following principles must be followed for a proper API design:

  1. You MUST not remove anything.
  2. You MUST not change the effects of the API.
  3. You MUST not make optional things required.
  4. Newly added things must be optional.

Acceptable means of compliance

1. You MUST not remove anything

For example both resource paths and payload items should be kept in parallel when they should be replaced for a grace period.

2. You MUST not change the effects of the API

When calling an endppoint does particular things, those things must not change in an unecpected manner. For example your API must not suddenly send an E-Mail to a customer when you initially didn't.

3. You MUST not make optional things required

Should be obvious. If the initial API didn't require a birth date but now suddenly does, it's bad and breaking for consumers that didn't provide the birth date or even built there processes around the fact that the bd is not necessary.

4. Newly added things must be optional

If you add a feature, parameter, or field to a payload, it must be optional. Introducing required fields would be a breaking change apparently.