what is an API

It's about that part of the code that's exposed to the public, the public API ...

When you need to change it, you might have to go through an API review board. Generally they will reject any changes that will make the API incompatible with previous versions. Cause this translates to having all the clients of the API change their code against your new API version.

There are cases when keeping the API compatible will be so difficult and add/or so much technical debt that the review board will accept version incompatible changes. They will work with the field engineers to understand what clients feel about this change and with the PM so that the next product version (the one shipping the version incompatible API) increments its major number.

It's not only the changes to and the removals from the API that should be reviewed by the API, it's also the additions. If the additions are badly designed, you'll still have to stick to them in the future, cause that's what public in public API obeys you to.

Yet there is another type of change that must be brought to the attention of the board: not an API change, but a behavioural change. Why bother then? Cause while clients' code will still compile, it will stop functioning as expected any more. And the only way to communicate this is through the API documentation.

Here is an example: a login API that changes from querying the company ActiveDirectory in favor of OpenID.

We should stop thinking about the API as just a set of classes and their methods. It's also the behaviour that's triggered when using those classes and methods.