Lesson 12 / 24

Why APIs Need Versioning

Evolving an API without breaking clients who are already using it.

You don't control the client

Unlike an internal library, you can't force every consumer to upgrade at once — mobile apps sit on old versions for months, third parties integrate once and forget. A breaking change to a shared endpoint breaks all of them simultaneously.

Additive vs breaking

Adding a new optional field or endpoint is usually safe without a version bump. Renaming/removing a field, changing a type, or changing status codes is breaking — that's what versioning exists to manage.

Version from day one

Even a v1 prefix with no plans for v2 costs nothing now and saves a painful migration later once real clients depend on you.