Why API versioning strategy is important

Azure API Management

Fiodar Sazanavets

Senior Software Engineer at Microsoft

Introduction to API versioning

Versioning intro

Azure API Management

API versioning fundamentals

Versioning analogy

  • Used when breaking changes would confuse riders

  • While the new line is built, passengers keep using the old one

  • Revisions are like maintenance tune-ups on the same line

    • Fixing tracks, adding signage, smoothing the ride

  • In APIM:

    • Versions live inside a version set
    • Revisions let you edit, test, and mark one as current
Azure API Management

Version signposting

  • Three version signposting strategies are supported:
    • Version can be declared in the URL path
    • Version can be specified in the request header
    • Version can be specified in URL query string
  • Versioning strategy needs to be consistent

URL path versioning

Header versioning

Query string versioning

Azure API Management

Version vs revision

Version vs revision

Azure API Management

Canary releases

Canary release

  • Outcomes:
    • If feedback is good -> mark the revision as current
    • Bad -> roll back to the previous revision

  • Like a kitchen test: serve a new recipe to a few tables first

  • In APIM:

    • Create a new revision and test it privately
    • Expose it to a limited audience (pilot product or subset of callers)
    • Target a specific revision via a special URL with the revision number

  • Railway metaphor: testers ride the "maintenance track" without affecting the main line

Azure API Management

Key concepts to remember

  • When to use versions vs revisions
  • Configuring version scheme
  • Rolling changes forward and back

API Management

Azure API Management

Let's practice!

Azure API Management

Preparing Video For Download...