All 15 API Versioning questions
More in API Versioning
How can feature flags be used as an alternative or complement to formal API versioning for rolling out changes gradually? How can you version a single controller action to support multiple API versions without duplicating the entire controller class? What's the difference between versioning a REST API's contract versus versioning its underlying data model, and why does that distinction matter? What is the 'tolerant reader' pattern, and how does it reduce the need for frequent API versioning? How do you handle database schema changes that need to support multiple concurrently deployed API versions during a migration window? How does API versioning strategy differ for internal microservice-to-microservice APIs versus public-facing external APIs?
Advertisement
Back to results for “API Versioning”
.NET › API Versioning

What are the trade-offs of versioning an entire API at once (global versioning) versus versioning individual endpoints independently?

Advanced

Answer

Global versioning (bump the whole API to v2 even if only one endpoint changed) is simpler to reason about and communicate but forces clients to migrate everything at once, even unaffected endpoints. Independent endpoint versioning (only the changed endpoint gets a new version while others stay stable) minimizes unnecessary client churn but increases complexity in routing, documentation, and mental overhead of tracking which specific endpoints are at which version.
// Global versioning: entire API bumps together
// /api/v2/products  /api/v2/orders  /api/v2/customers (all v2, even if only products changed)

// Independent versioning: only the changed resource bumps
// /api/v1/orders  /api/v2/products  /api/v1/customers (mixed versions)
Real-world example A large platform API with dozens of resource types adopts independent endpoint versioning specifically to avoid forcing every integrator to re-test their entire integration whenever any single unrelated endpoint changes.

Common follow-ups: Which large public APIs use each approach (e.g., Stripe vs GitHub)?;How does independent versioning complicate client SDK generation?

RESTful Web APIs & Controllers;Microservices & Distributed Architecture Patterns
All 15 API Versioning questions