Quick guide to API Versioning Strategies to avoid breaking changes pros and cons of each strategie non exhaustive

Here's 5 strategies for API versionning, the most popular strategies : URI via Path Param, Custome header via Accept

Coordinating a breaking change is not easy

First identify if it's a Breaking changes:

• Non-Breaking changes (No effect on existing API)
• Breaking changes (Not backword compatible, Versioning helps transition) -->  HTTP Status 500 Relaese changes and still support the older one
• Overhaul (All new API, Beyond versioning)

API Versioning typical lifespan:
v1 - first release
v2 - second release, notify consumers v1 version is deprecated
v3 - remove v1 (optional)

Recap for API lifecycle :

Semantic Versioning 2.0.0 smever.org

API URLs typically use MAJOR versions

API Versioning Strategies :

• URI  (via Path Param): Version is embededded in URI --> v1, v2 works with caching where is key
• Cons : 
• creates whole new tree in each version, require testing and validation.
• URI itself is changing 
• Pors  : developer friendly
• Content Negotiation via Media Type :  like application/json, used server side to determine what version to use for call
• Define vendor specific media types
• Example : application/vnd.softwarquality.v1+json 
• application/vnd.softwarquality.v2+json 
• Pors : URI does not change.
• Cons : non standard media type used
• Header via Custom header (Accept): Define custom header for version information
• Example : Accpet-version : v1,  and define a value like v1 or v2
• Server neds to look for the header and value to determine which version to use
• Pors : URI  does not change, better than overloaded media type
• Cons : 
• Request parameter (Query Param): parameter with version information, parsed with to server to determine which version to use
• Example : /api/products?version=v1
• Pors : URI does not change.
• Cons : routing request more difficult 
• No strategy rewrite

Most popular strategies : URI, Custom header

Conculsion : 
INMO Custom header is the best strategie, since URL resource is unique even if we change API version.
Please add in the comment section other pros and cons.