jeudi 21 mai 2020

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 ParamCustome 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.

Aucun commentaire:

Enregistrer un commentaire

to criticize, to improve