URL: https://rol.redhat.com/rol/app/courses/do240-2.11/pages/ch02s05
Reporter RHNID:
Section: 5 - Introducing API Versioning
Language: en-US (English)
Workaround:

Description: Maybe it is just my congitive style (and happy to receive feedback) but I think the intro has some issues.

To my undestarnding it writes in sequence:
1. Versioning is used to release backward-incompatible changes to your API without breaking client code
2. An example of backward incompatible change is "remove an API resource field" and that breaks the code.
3. Use versioning if the code must change before using the new version.

Reading this in reverse order would be close to:

3. Release a new version if the code must change
2. The code must change if you remove a filed from an API answer because it is backward incompatible.
1. Release a new version for any backward incompatible and that will not break your code.

The code either breaks or does not break. We can not have both.

Maybe this is just a language gap issue and happy to receive any feedback.