Pexels stock image for "versioned API docs" - Photo by ThisIsEngineering on Pexels
APIs are the connective tissue of modern software, but they are not static. They need to evolve to add features, fix bugs, and improve security. This constant change presents a challenge: how do you update your API without breaking the applications that depend on it? The answer lies in a solid versioning strategy, communicated clearly through well maintained versioned API docs.
Without a clear plan, even a small change can cause major headaches for your users. A good versioning policy, however, builds trust and stability, allowing developers to adopt new features on their own schedule. This guide walks through the core concepts of API versioning and explains how to create the versioned API docs your developers need to succeed.
At its core, API versioning is the practice of managing changes to your API in a way that doesn’t surprise consumers. It involves creating distinct, stable contracts (versions) so that you can introduce new functionality, or even breaking changes, without disrupting existing integrations.
Before you pick a method, you need a versioning strategy. This is your overall policy for how and when you introduce new versions. A good strategy considers how to make changes backward compatible whenever possible to avoid creating new versions unnecessarily. Google, for instance, recommends minimizing version creation by designing for backward compatibility first. Your strategy should clearly define what constitutes a breaking change and how you will manage the lifecycle of each version, from release to retirement.
There are several common ways to implement API versioning. Each has its own trade offs, and the best choice depends on your specific needs.
This is one of the most straightforward approaches. You simply include the version number directly in the URL path.
Microsoft Graph uses /v1.0/ for its stable endpoints and /beta/ for previews.
Twilio embeds a date in the path, like for April 1, 2010.
Shopify also uses a date based path, for example naming versions by year and month, like a July 2024 release.
This method is highly visible and makes it easy to route requests to the correct backend service.
Another explicit method is to include the version as a query parameter in the URL. This is a common pattern for many large enterprise APIs.
Many Microsoft Azure services require an api-version query parameter, with the value set to a release date like January 1, 2024. Requests that omit it are often rejected with an error.
This approach keeps the core resource path clean, though some caching proxies may not handle query strings as effectively as URL paths.
A popular and flexible method is to specify the API version in an HTTP request header. This keeps the URL clean and separates the versioning concern from the resource’s location.
GitHub uses a custom header, X-GitHub-Api-Version, with the value set to a date like November 28, 2022.
Stripe uses the Stripe-Version header, and its SDKs automatically pin requests to a specific version.
Heroku uses the Accept header with a custom media type, like application/vnd.heroku+json; version=3.
Beyond the mechanism, you need a naming scheme. Two popular choices are Semantic Versioning (SemVer) and Calendar Versioning (CalVer).
Semantic Versioning uses a MAJOR.MINOR.PATCH format. A MAJOR version bump signals an incompatible, breaking change. This is widely used for SDKs and libraries because it clearly communicates the impact of an upgrade.
Date based Versioning (or CalVer) uses the release date, such as a YYYY MM DD format. This is used by providers like Shopify and GitHub for their APIs. It makes the age of a version immediately obvious and aligns well with scheduled, periodic releases.
A less common but powerful approach is consumer driven contract testing. Here, the focus shifts from the provider dictating versions to consumers publishing their expectations. Tools like Pact help providers verify that any new changes won’t break existing consumer contracts, which can reduce the need for explicit versioning in the first place.
Once you have a strategy, developers need a clear way to select a version. Relying on implicit behavior can lead to unexpected breakages down the line.
The best practice is specifying a per request version. This means the client explicitly states which version it wants with every single API call, usually via a path, query parameter, or header. This eliminates ambiguity and ensures that a change to a default setting on the provider’s side doesn’t suddenly break a client’s integration. Stripe and GitHub both encourage this pattern. If you ship multiple products or surfaces, consider versioning each independently in your documentation with a product switcher.
Many APIs have a default API version that is used if a client doesn’t specify one. While this can seem convenient, it’s risky. For example, if Shopify changes its oldest supported version, requests without a specified version will “fall forward” automatically, which could introduce breaking changes the consumer wasn’t prepared for. Explicitly specifying the version is always safer. A dedicated version header is one of the clearest ways to implement this, as seen with Stripe’s Stripe-Version and GitHub’s X-GitHub-Api-Version.
A versioning strategy is incomplete without clear policies for managing the API’s lifecycle.
Your breaking change policy sets expectations for your users. It should define what counts as a breaking change and the timeline for introducing one. GitHub, for example, only introduces breaking changes in new date named versions and supports an old version for at least 24 months.
An API version upgrade is the process for consumers moving from one version to the next. This should be a planned, well documented event. Your goal is to make this process as painless as possible.
Developers must always know which is a supported API version. Providers should publish a clear list of active versions and their expected retirement dates. Shopify provides a public schedule of its quarterly releases and their support windows, ensuring developers have at least nine months of overlap to migrate.
Finally, a deprecation policy outlines how you’ll retire old versions. This includes a notice period and a “sunset” date when the version will be turned off. The OWASP API Security Top 10 highlights the risk of not tracking deployed versions, as forgotten endpoints can increase your attack surface. Using standardized Deprecation and Sunset HTTP headers can help communicate these timelines programmatically. You can also surface deprecation timelines directly in your docs with a persistent announcement banner.
A versioning strategy is only as good as its communication. This is where high quality, accurate, and easy to navigate versioned API docs become your most important asset. Adding AI search to your docs can also help developers find the right version-specific answers instantly.
Out of date documentation can be more damaging than no documentation at all. Every time you release a new API version, your docs must be updated to reflect it. This includes the API reference, guides, and code examples.
Maintaining multiple versions of your documentation can be complex, but it’s essential. Platforms like Fern are designed to handle this, making it simple to generate version-aware docs and SDKs directly from your API specification. Having clear, accessible, and versioned API docs is the foundation of a great developer experience.
A changelog is a chronological, human readable log of all notable changes for each version. It should be detailed and easy to filter. Stripe maintains a comprehensive API changelog that includes historical breaking changes, which is an invaluable resource for developers planning an upgrade. A great changelog is a critical component of useful versioned API docs. For an example, see how to set up an API changelog in Fern.
While a changelog says what changed, a migration guide explains how to handle it. This is a step by step set of instructions to help developers move from an older version to a newer one safely. A good guide includes code samples, details on breaking changes, and a clear checklist. Combining detailed migration guides with your other versioned API docs dramatically reduces the friction of upgrading.
If you are planning a versioning rollout, tools can generate version-aware docs and migration snippets automatically. For more complex needs, some teams offer hands-on migration assistance to ensure your users have a smooth transition.
Managing API evolution is a critical part of building a successful platform. By choosing a clear versioning strategy and committing to excellent communication through comprehensive versioned API docs, you empower developers, build trust, and ensure your API can grow for years to come. If you have strict compliance or networking requirements, you can also self-host your documentation.
Versioned API docs are documentation websites that are tied to specific versions of an API. They allow developers to view the correct endpoints, request fields, and response structures for the exact API version their application is built on, preventing confusion and errors when an API changes over time.
There isn’t one single “most common” strategy, but URL path versioning (e.g., /api/v2/users) is very popular due to its simplicity and visibility. However, header versioning and query parameter versioning are also widely used by major API providers like Stripe, GitHub, and Microsoft.
The best practice is to introduce breaking changes only in a new major version (e.g., moving from v1 to v2). You should have a clear breaking change policy that gives developers a long notice period, provides a detailed migration guide, and supports the old version for a reasonable amount of time (often 12 to 24 months).
Specifying the version on every request is safer because it makes the client’s dependency explicit. If you rely on a default version, the API provider might change that default, which could break your application without you making any changes on your end.
A changelog is a chronological list of what changed in each version (e.g., “Added new_field to User object”). A migration guide provides step by step instructions on how to update code to accommodate those changes (e.g., “Replace old_parameter with new_parameter in all calls to the /users endpoint”).
Using a modern documentation platform is the best way. Tools like Fern can automatically generate interactive, versioned API docs directly from your OpenAPI or Fern Definition. This “docs as code” workflow ensures your documentation always stays in sync with your API.
Semantic versioning (SemVer) is excellent for libraries and SDKs where the impact of changes (MAJOR, MINOR, PATCH) is critical for dependency management. Date based versioning (CalVer) is often preferred for web APIs because it clearly indicates the age of a version and aligns well with regular, scheduled release cadences.
