Add blog post: Global vs independent API versioning#255
Add blog post: Global vs independent API versioning#255riboflavin wants to merge 3 commits intoRedocly:mainfrom
Conversation
![redocly[bot]](https://avatars.githubusercontent.com/in/348054?s=60&v=4){kind=small}
There was a problem hiding this comment.
marketing-site AI Review: 🟢 Completed
Reunite Bot has reviewed your changes and found 5 potential issue(s).
Note
Low Risk
This PR only introduces a new markdown file for a blog post. It does not affect any application code or system functionality.
Overview
Adds a new blog post titled "Is it better to use a global API versioning strategy or version each endpoint independently?". The post explores the trade-offs between global API versioning (prioritizing coherence and snapshots) and independent endpoint versioning (favoring developer agility). It also discusses group-based versioning as a hybrid approach and the nuances of API evolution versus formal versioning.
|
|
||
| Independent endpoint versioning often relies on content negotiation or custom headers to avoid creating a sprawling directory of URL paths. GitHub has famously used custom media types (e.g., `Accept: application/vnd.github.v3+json`) to allow clients to request specific API behaviors. This keeps the URL namespaces clean (`/users` is always `/users`) but moves the complexity into the request headers. | ||
|
|
||
| Using headers facilitates the granular release of features, such as GitHub's [preview media types](https://github.blog/changelog/2021-10-14-rest-api-preview-promotions/), but it complicates testing and observability. A developer cannot simply paste a URL into a browser to see the response; they must configure headers for every request. As Zalando notes in their [RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/), if you must version, media types are preferred for REST purity, but they demand more sophisticated tooling and documentation than simple path-based global versions. |
There was a problem hiding this comment.
Header-based versioning hinders security observability. WAFs and SIEMs often prioritize URL paths for filtering; moving version metadata to headers makes it harder to detect and block attacks targeting specific legacy contract versions.
|
|
||
| Before committing to a complex versioning scheme, consider if you need to version at all. Many teams conflate "changing the API" with "versioning the API." | ||
|
|
||
| The [concept of API evolution](https://redocly.com/docs-legacy/api-registry/resources/versioning-strategies) suggests that most changes should be additive. You add a new field, a new optional parameter, or a new response type. These changes are backward compatible and do not require a version bump. |
There was a problem hiding this comment.
Additive evolution can lead to OWASP API6: Mass Assignment. Warn that adding new input fields requires strict allowlists in the backend to prevent accidental exposure or modification of sensitive internal object properties.
|
|
||
| You must define how long a version remains supported. Microsoft Graph commits to a [24-month minimum notice](https://learn.microsoft.com/en-us/graph/versioning-and-support) before retiring a GA version. Shopify guarantees 12 months. | ||
|
|
||
| If you version endpoints independently, tracking these timelines becomes geometrically more difficult. You must track usage metrics per endpoint to know when it is safe to turn one off. With global versioning, you can monitor traffic based on the version header or URL path, giving you a clear signal when a `2021` snapshot has zero traffic. |
There was a problem hiding this comment.
Explicitly link tracking difficulties to OWASP API9: Improper Inventory Management. Failing to identify and retire unmanaged, deprecated endpoints (Zombie APIs) significantly increases the organizational attack surface.
| title: Global vs independent API versioning strategy | Redocly | ||
| description: Learn the trade-offs between global API versioning and independent endpoint versioning, including coherence, agility, and hybrid approaches for complex systems. | ||
| author: adam-altman | ||
| publishedDate: 2026-04-24 |
There was a problem hiding this comment.
The publishedDate is set to a future date (2026-04-24). Please verify if this is intentional for scheduling or if it should be corrected.
|
|
||
| Before committing to a complex versioning scheme, consider if you need to version at all. Many teams conflate "changing the API" with "versioning the API." | ||
|
|
||
| The [concept of API evolution](https://redocly.com/docs-legacy/api-registry/resources/versioning-strategies) suggests that most changes should be additive. You add a new field, a new optional parameter, or a new response type. These changes are backward compatible and do not require a version bump. |
There was a problem hiding this comment.
The absolute link to [concept of API evolution] points to deprecated /docs-legacy/ documentation. Update to a current resource or relative link to avoid outdated content.
2 participants
What/Why/How?
Reference
Testing
Screenshots (optional)
Check yourself
Security