What is API versioning?
API versioning is the practice of maintaining multiple stable versions of your API simultaneously, so that existing integrations continue to work when you make changes. When you release /v2/ of an endpoint with a different response shape, /v1/ stays live for customers who haven't updated their integration yet.
Without versioning, any breaking change — renaming a field, removing an endpoint, changing a response format — risks breaking every integration your customers have built. Versioning gives you the freedom to evolve your API while honouring commitments to existing consumers.
This is relevant primarily for public APIs with external consumers. An internal API used only by your own frontend is a different situation — you control both sides of the contract.
When does your app need it?
- You have a public API that third-party developers or customers integrate against
- Enterprise customers have built internal tooling on top of your API and need stability guarantees
- You're planning to make breaking changes (rename fields, restructure responses, change authentication)
- Your API is used by mobile apps that can't be force-updated instantly
- You've committed to API stability as part of a partner or reseller agreement
- You're building towards a developer ecosystem and want to attract integrators with confidence
How much does it cost?
Adding API versioning typically adds 4–8 hours of development — roughly $1,000–$2,000 AUD.
Lower end: URL-based versioning (/v1/, /v2/) with version routing middleware, applied to an existing API. Straightforward if the API is well-structured.
Higher end: Version routing plus deprecation notices (headers warning consumers that /v1/ will sunset on a specific date), version-specific documentation, a sunset policy and communication process, and the ongoing maintenance cost of running two or more versions of handler logic in parallel.
How it's typically built
The simplest and most common approach is URL versioning: prefix all routes with /v1/ and route requests through version-specific handler files. When /v2/ is needed, a new set of handlers is added; /v1/ handlers remain unchanged.
In Express or Fastify, this is a router per version. In Next.js API routes, it's a folder structure under /api/v1/ and /api/v2/. In each case, shared business logic lives in service layer functions that both versions can call — only the request parsing and response shaping differs.
Header-based versioning (Accept: application/vnd.api+json; version=2) is an alternative that keeps URLs clean but is harder for consumers to work with. Most developer APIs use URL versioning for its simplicity.
Deprecation is a process, not just a code change: Sunset and Deprecation response headers, documentation updates, and direct communication to registered API consumers before the old version is retired.
Questions to ask your developer
- Does your API have external consumers today? If it's internal only, you don't need formal versioning — just change it and update your frontend.
- What's your deprecation timeline? How long will old versions be maintained? This needs to be communicated clearly before you commit to it.
- Is URL or header versioning more appropriate? URL versioning is simpler for consumers and easier to document.
- How will consumers know when a version is being deprecated? Sunset headers, email to registered developers, documentation — plan this from the start.
- Does your OpenAPI documentation support multiple versions? Keeping docs in sync across versions requires tooling discipline.
See also: Public API and webhooks · App cost calculator