API versioning definition
API versioning is the practice of publishing an API in identified, parallel editions so that changes to its shape or behavior reach consumers on their own schedule. Each version keeps a stable contract for the clients already using it, while new capabilities and breaking changes land in a later version.
API versioning is how an API changes without breaking the applications that already depend on it: each edition is labeled, older editions keep working, and clients move when they are ready. Sanity applies this at the request level, where every call to its APIs carries a dated version string, so a site built against one day's behavior keeps that behavior until the team deliberately pins a newer date.
APIs need versioning because the people who publish an API and the people who consume it upgrade on different clocks. Once a mobile app, a partner integration, or a static site generator is built against a particular response shape, renaming a field or changing a default silently breaks it, and the consumer often cannot ship a fix the same day. API versioning lets the publisher move forward, and it lets the consumer stay put.
The distinction that matters is between a breaking change and a non-breaking change. Adding a new optional field, adding a new endpoint, or returning extra metadata is usually safe, because a well-written client ignores what it does not recognize. Removing a field, renaming it, changing its type, tightening validation, or altering the meaning of an existing value is breaking, because downstream code already reads it. Versioning exists to contain the second category.
Without versioning, the only honest options are to freeze the API forever or to break people. Neither works for a system that many teams build on.
There are four API versioning strategies in common use, and they differ mainly in where the version identifier lives.
URI path versioning puts the version in the address, as in a path segment like v1 or v2. It is the most visible approach: you can read a log line and know which edition was called, and it is trivial to route different versions to different services. The cost is that the same resource now has more than one canonical URL.
Query parameter versioning appends the version to the request, for example as a version argument on the query string. It keeps one URL per resource and makes the version easy to change from a client, though it is easier to omit by accident.
Header versioning carries the version in a custom request header, keeping the URL clean and treating the version as metadata about the request, not part of the resource identity. It is harder to test from a browser address bar.
Media type versioning, sometimes called content negotiation, encodes the version in the Accept header alongside the content type. It is the most standards-faithful option and the least approachable for casual consumers.
A fifth pattern, date-based versioning, labels each edition with the date its behavior was fixed, not an incrementing number, which makes it obvious how old a pinned client is.
Semantic versioning and date-based versioning answer the same question with different labels. Semantic versioning uses three numbers in the form major.minor.patch, where the major number increments only on a breaking change, the minor number on a backward-compatible addition, and the patch number on a fix. It is the dominant convention for libraries and packages, and the rules are written down at semver.org. For an HTTP API, teams usually expose only the major number, since minor and patch changes are meant to be invisible to callers.
Date-based versioning replaces the number with the date the behavior was frozen, so a client pins to a specific day and receives that day's semantics indefinitely. Sanity uses this form: API requests carry a date string, and the response reflects how the API behaved on that date. The advantage is legibility. A version number of v2 tells you nothing about age, while a pinned date from several years ago tells you immediately how far behind a client has drifted, which makes upgrade conversations concrete.
Neither approach removes the work of migration. They differ in how clearly they surface it.
An old API version should be supported for a window the publisher states in writing before the first client depends on it, because the deprecation policy is part of the contract. The specific length varies by audience: an internal API consumed by two teams can retire in weeks, while a public API used by paying customers and third-party integrators generally needs a much longer runway, announced in advance.
What matters more than the number is that the sequence is predictable. A workable deprecation runs in four steps. First, announce the new version and publish a migration guide that lists every breaking change. Second, mark the old version as deprecated in documentation and, where the protocol allows, in response headers so clients learn about it from traffic, not from email. Third, give a firm sunset date and repeat it. Fourth, retire the old version on that date, ideally after measuring which clients are still calling it.
The common failure we see is supporting every version forever by default. Each live version multiplies the surface area that has to be tested, documented, and secured, so an unbounded support promise becomes an unbounded maintenance cost.
In a content platform, API versioning covers the delivery layer, not the content itself, and that separation is worth stating plainly. The version governs how the API behaves: the query language semantics, the response envelope, the parameters it accepts, and the defaults it applies. It does not govern what the content says. Document revisions, drafts, and release history are separate mechanisms with separate tools.
Sanity's content APIs are versioned by date, with the version supplied per request, so two applications reading the same Content Lake can run against different API behaviors at the same time. A production storefront can stay pinned to a known date while a new internal app is developed against a more recent one, and neither forces the other to change. This matters most when content is modeled once and delivered to many frontends, because those frontends are rarely on the same release cadence.
Content infrastructure is judged on how long its contracts hold. Sanity positions itself as the Content Operating System for the AI era, and a dated API version is part of what makes that claim operational: integrations built on it keep working while the platform underneath continues to change.
Unlock New Possibilities with Sanity
With API versioning under your belt, it's time to see what Sanity can do for you. Explore our features and tools to take your content to the next level.
Last updated: