# Versioning Strategies — REST API Design: Resources, Status Codes and Security

Source: https://www.skillbyai.com/en/restapi/api-versioning-strategies

> Compare URI, header and media-type versioning strategies and plan deprecation with a clear migration window.

## URI versioning

The most common approach in practice — visible, cacheable, and easy to route by, at the cost of duplicating a URI across versions.

```text
GET /v1/orders/482
GET /v2/orders/482
```

## Header-based versioning

Keeps the URI stable and treats a version as another content-negotiation axis — favored by API purists, but harder to test in a browser bar or curl by hand.

```http
GET /orders/482 HTTP/1.1
Accept: application/vnd.example.v2+json
```

## Whatever you pick, support overlap

Run at least two versions side by side with a published deprecation date for the old one — never flip a version overnight with no migration window.

**Quiz:** Which of these is a *breaking* API change that needs a new version?

- [ ] Adding a new optional field to the response
- [x] Renaming an existing response field
- [ ] Adding a new endpoint
- [ ] Fixing a typo in documentation

*Answer:* Renaming an existing response field. Renaming or removing a field breaks any client reading the old name; additive changes like new fields or endpoints are typically safe.