Lesson 12 / 25
Why APIs Need Versioning
Learn why APIs need versioning, which changes are breaking and how to evolve an API without hurting existing clients.
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.