Skip to content
BENIBIX Learn

API Versioning

Development🔌 APIsAPI Design Practices

Also known as API Version, v1, Versioned API

Version numbers on an API, so changes do not break the apps that use it.

Think of it like

Think of it like a new edition of a book. The old one stays on the shelf for a while.

Example

Jack renames a field from name to fullName. He ships it as /v2/users and keeps /v1/users working for a year.

Why it matters

Other people's apps depend on your API. Breaking them without warning loses their trust and their users.

Definition

API versioning gives an API a version number, like v1 or v2. You can then change it without breaking the apps that use it. The version often sits in the address, like /v1/users and /v2/users. Old apps keep calling v1 while new apps move to v2. A small change that adds a field can stay in the same version. A change that removes or renames something needs a new one.

Example code

http
GET /v2/users/42 HTTP/1.1
Host: api.example.com
The v2 in the address picks the newer version.

Common mistake

Making a new version for every small change. Add fields freely; only a breaking change needs a new number.

Key takeaways

  1. 1
    Change without breaking. Old apps keep working.
  2. 2
    Often in the address. /v1/, /v2/.
  3. 3
    Only for breaking changes. Adding is fine.