What is API Version?

  1. How to control spec of the API Contract (schema or model) ?
  2. How to support multiple spec of this contract at the same time - so clients (developers) can switch from one spec to another at their pace
  3. How to introduce an important feature which could break existing customer experience?
  4. How to deprecate something created x years ago?

One answer to all the above questions is - API versioning

In API world, versioning is used for the API contract.

There are multiple strategies used for API versioning. In some cases, you may not need versioning at all. Here are a couple of ways.

1. Conventional Versioning - URI Path

Version numbers can be in the API path. Eg. /v1/invoice. This is the most common way people follow. Whenever they are introducing a breaking (contract) change, they introduce /v2/invoice. Conventional Versioning


  1. Needs separate endpoint/swimlane/backend for each version. Because of this as a provider you cannot serve too many versions at the same time.
  2. Increases maintenance & infrastructure costs. Think about API Explorer/playground, documentation, backward compatibility
  3. As a provider you really need to test for every change you introduce, cause you wouldn’t be changing version number that frequently. This is a huge restriction if you are selling API as a product.
  4. Even if you support versioning in major.minor format (eg. v1.06), you need separate API endpoints for each version.


  1. Pretty standard & needs no introduction
  2. Purging older versions is like dropping a swimlane / turning it off in API Gateway.

For most of the use cases, just this strategy is good enough.

2.Advanced Versioning - over HTTP Header

Stripe is very popular for their state of the art APIs. Stripe also supports multiple versions of APIs to allow their consumers to migrate to latest at their own pace. How do they do it? They have a fantastic blog post on versioning strategy & how they do it.

In this strategy, version string is passed through a HTTP Header. If you use Semantic version (Major.Minor.Patch) format, it will be more extensible. There is a one time setup. After that, we could support as many api versions as we can without much of the ongoing effort. Versioning is supported through a special HTTP Header - version. For eg. for Stripe it is Stripe-Version. The format can be anything.

Advanced Versioning


  1. Over engineering for some use cases, where requirements are well understood or clear OR your APIs are internal.
  2. There is some upfront work


  1. This will make API Providers fearless! They can support 100s of versions without any infrastructure overhead.
  2. If your product is API - then this is the strategy - you could keep shipping new features without impacting existing customers. Imagine you have a converyor belt for shipping any kind of object

Version Format

I like minor variation to semantic version that includes date. For eg. -x.y.z-YYYY.MM.DD

x is major,
y is minor &
z is patch
YYYY.MM.DD is the date this version x.y.z got released to customers

This date is very useful to me if I am a customer of the API - that how old my version is & should I be using latest version.

Example HTTP Header api-version: 01.10.23-2021.08.02


> GET /v1/invoice HTTP/2
> Host: api.your-service.com
> user-agent: insomnia/2021.3.0
> content-type: application/json
> authorization: Bearer X3hqbfgzjwkctzl35ws17cCMvBLnSUnMdCMeB2AAsBM
> accept: application/json
> api-version: 01.10.23-2021.08.02


| {
|     "id": "in_gLnSUnAQqbWA"
|     "customerId": "c_ctzl35ws17cCM",
|     "subTotal": {
|          "amount": "101.22",
|          "currency" : "usd"
|     },
|     "salexTax": {
|          "rate" : "9.25",   
|          "amount": "9.36",
|          "currency" : "usd"
|     },
|     "Total": {
|          "amount": "110.58",
|          "currency" : "usd"
|     },
|     "items" : [ 
|          {},
|          {}
|     ]
| }

< HTTP/2 200 
< date: Sat, 24 Jul 2021 03:02:24 GMT
< content-type: application/json
< api-version: 01.10.23-2021.08.02


  1. API Versioning by Stripe
  2. Which versioning strategy might be right for you
  3. API Versioning has no right way
  4. All about Semantic Version Format