API Versioning

In Turkish: API sürümleme

Updated September 30, 20262 min read

In short

API versioning is the practice of labeling and managing changes to an API so existing clients keep working while new versions add or change features.

What is API versioning?

API versioning is a way to evolve an API without breaking the apps that already depend on it. Once other developers have built against your API, renaming a response field or removing an endpoint can break their code, so you release breaking changes under a new version, such as v2, and keep the old version running for a while.

There are several common ways for a client to say which version it wants. URL path versioning puts it in the path, like /v1/users, which is the most visible approach and the easiest to test, while header versioning uses a custom header or the Accept header, and query parameter versioning uses something like ?version=2. Some APIs use release dates instead of numbers, such as 2026-09-30, so each client is pinned to the behavior of a specific release.

Think of versions like editions of a textbook: a school using the second edition can keep teaching from it after the third edition reorders the chapters, until it's ready to switch. Versioning matters most for public APIs, mobile apps that users don't update right away, and partner integrations, where you can't update every client at once.

API versioning is often confused with semantic versioning of software packages. Semantic versioning uses three numbers like 2.4.1 to signal breaking changes, new features, and fixes, while public APIs usually expose only a major version, because only breaking changes require clients to act. Adding optional fields or new endpoints is backward compatible and doesn't need a new version, but removing or renaming fields or changing their types does, and old versions should be retired with advance notice, for example through the Deprecation and Sunset response headers.

Key takeaways

Versioning lets an API make breaking changes without breaking existing clients.
Common approaches put the version in the URL path, a header, or a query parameter.
Adding optional fields is backward compatible; removing or renaming fields is a breaking change.
Public APIs usually expose only a major version, such as v1 or v2.
Retire old versions with clear timelines and headers like Sunset.

Example

Requesting specific API versions with curlbash

# URL path versioning: the version is part of the address
curl https://api.example.com/v1/users/42
curl https://api.example.com/v2/users/42

# Header versioning: same URL, version sent in a header
curl https://api.example.com/users/42 \
  -H "Accept: application/vnd.example.v2+json"

# Query parameter versioning
curl "https://api.example.com/users/42?version=2"

# Date-based versioning: pin the client to a release date
curl https://api.example.com/users/42 -H "Api-Version: 2026-09-30"

Readers ask

What is the best way to version an API?

There is no single best way, but URL path versioning such as /v1/ is the most common because it is simple, visible, and easy to cache and test. Header-based versioning keeps URLs clean but is harder to try out in a browser.

When should I create a new API version?

Create one only for breaking changes, such as removing or renaming fields, changing data types, or adding required parameters. Backward-compatible changes like new optional fields or new endpoints can ship in the current version.

How long should old API versions be supported?

It depends on your users, but public APIs commonly give at least 6 to 12 months of notice before retiring a version. Announce the timeline, send deprecation headers, and track which clients still use the old version.