All 15 API Versioning questions
More in API Versioning
Why is API versioning important for a production web API? What are the main strategies for versioning an ASP.NET Core API (URL, query string, header, media type)? How do you implement URL-based API versioning using the Asp.Versioning.Mvc package in ASP.NET Core? How do you communicate API version deprecation to clients using response headers? How do you version an API's OpenAPI/Swagger documentation to show separate docs per version? How does GraphQL's approach to API evolution differ from REST's typical versioning strategies? What HTTP status code and response should an API return when a client requests a version that no longer exists or was never supported? 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?
Advertisement
Back to results for “API Versioning”
.NET › API Versioning

How does semantic versioning (SemVer) inform decisions about when to bump an API's major, minor, or patch version?

Intermediate

Answer

Semantic versioning conventions (MAJOR.MINOR.PATCH) map naturally to API changes: a MAJOR bump signals breaking changes (removed fields, changed response shapes, incompatible behavior), a MINOR bump signals backward-compatible additions (new optional fields, new endpoints), and a PATCH bump signals backward-compatible bug fixes with no contract change. Most public API versioning schemes (like /api/v1, /api/v2) only expose the MAJOR component externally, treating MINOR/PATCH as internal implementation detail that doesn't require client action.
// Externally exposed: only major version
// /api/v1/products  /api/v2/products

// Internally tracked via SemVer in release notes:
// v1.3.2 -- patch fix, no client action needed
// v1.4.0 -- new optional field added, backward compatible
// v2.0.0 -- breaking change, new URL segment required
Real-world example An API's changelog documents every release using full SemVer internally (v1.4.2, v1.5.0) while only the major version (v1, v2) is ever reflected in the actual URL path clients call, keeping the versioning surface simple for consumers.

Common follow-ups: Should minor/patch versions ever be exposed in the URL?;How does this map to versioning conventions in package managers like NuGet?

RESTful Web APIs & Controllers;CI/CD Publishing & Deployment
All 15 API Versioning questions