API Versioning

Prefer evolving an API without a new version. Every supported version becomes another product to maintain and retire.

When to version

No new version for compatible changes:

• New endpoint
• New optional request property
• New response property (clients must tolerate unknown fields)
• Fix behavior to match the documented contract

New version for breaking changes which cannot be coordinated with all consumers:

• Remove or rename fields / endpoints
• Change types, meaning, validation or error behavior
• Make optional input mandatory
• Change authentication or workflow expectations

Strategies

There is no generally best version location. Choose one convention and apply it consistently. URL path versioning is usually the simplest and most discoverable option.

Attribute-controlled versioning

• URL Path Versioning
  • Example url: https://localhost:7142/v0.1/persons 
    • ✅ Simple and explicit
    • ✅ Easy to discover, route and document
    • ⚠️ Version becomes part of every resource URL
• Query String Versioning
  • Example url: https://localhost:7142/persons?api-version=0.1 
    • ✅ Keeps URI structure clean
    • ⚠️ Less visible to clients
    • ⚠️ Routing and caches must include the query parameter
• Header Versioning
  • Example url: https://localhost:7142/persons with Header api-version: 1.0
    • ✅ Keeps resource URLs stable
    • ⚠️Harder for clients to discover and test
    • ⚠️ Caches need an appropriate Vary strategy
• Media Type Versioning
  • Example url: https://localhost:7142/persons with Accept: application/vnd.application-info.v1+json
    • ✅ Decouples representation versioning from the URL
    • ✅ Useful when content negotiation provides a concrete benefit
    • ⚠️ More complex to document and implement
    • Use Accept for the requested response representation and Content-Type for the submitted request representation.

Physical Separation

• New Resource variant
  • Introduce a new resource alongside the old one (e.g., /persons and /persons-extended)
    • ✅No formal versioning
    • ✅ Appropriate when the concept or behavior genuinely differs
    • ⚠️ Do not use only to hide a breaking contract
• New Service Endpoint
  • Deploy a whole new application or service with a new domain or base path.
    • ✅Full isolation of versions
    • ✅Clean separation of concerns
    • ⚠️ Highest operational and migration cost

Implementation (.NET)

This official dotnet nuget enables the implementation of a nice api-versioning: https://github.com/dotnet/aspnet-api-versioning with good documentation https://github.com/dotnet/aspnet-api-versioning/wiki