# API Versioning

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

**Field:** Software Development  
**Category:** APIs  
**Also known as:** API Version, v1, Versioned API

## Think of it like

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

## 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

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

## Example code

```http
GET /v2/users/42 HTTP/1.1
Host: api.example.com
```

The v2 in the address picks the newer version.

## Why it matters

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

## Common mistake

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

## Three principles

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

## Related terms

- [Application Programming Interface (API)](https://learn.benibix.com/term/development/api)
- [API Endpoint](https://learn.benibix.com/term/development/endpoint)
- [OpenAPI Specification](https://learn.benibix.com/term/development/openapi)
- [REST API](https://learn.benibix.com/term/development/rest-api)
- [Contract Testing](https://learn.benibix.com/term/development/contract-testing)

---

Source: https://learn.benibix.com/term/development/api-versioning
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-19
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
