Every more complex API structures need versioning as developers and consumers may progress implementing and consuming changes at different paces.

Let's consider a sample API stack with two sample calls:

  1. GET api/sales/receipt/receiptid – returning receipt document for a given ID
  2. POST api/sales/create – accepting date, customerId, itemId to create sale document

The base URL for API are sales/receipt/receipted and /sales/create – respectively

A typical API versioning scheme should provide a major version number for each breaking change and a minor version for each non breaking version of each API.

For sake of simplicity you may provide a new version of API with each and every breaking change only. It would be easier to provide uniform change and expose all API endpoints every time at least one API method has change in a breaking method, or becomes deleted. Therefore a change in the API sales create method would trigger releasing a brand new version of whole API stack:

  1. GET api/v2/sales/receipt/receiptid
  2. POST api/v2/sales/create – accepting sale date, customerId, itemId, netprice

Make note that the first API call has not changed between versions, however because we’re sporting a simple one number versioning scheme, it makes sense to release a new version for all API calls just to ensure customer API compatibility level. The second API method has been enhanced with a net price as a required parameter.

We may adopt a following scheme going further

  • /api/method – the most recent version of API method
  • /api/v1/method – the first version of API method
  • /api/v2/method – the latest version of API method
  • /api/beta – the experimental unsupported version
Another approach that may be less taxing for consumers and developers involves versioning the media types instead of URI versioning
GET /sakes/receiptid HTTP/1.1
Accept: application/vnd.myname.v1+json
HTTP/1.1 200 OK
Content-Type: application/vnd.myname.v1+json
    "receipt": {
        "total": "100"

When we version the Media Type and extend the language, we go through Content Negotiation based on this header. The REST API would make use of custom vendor MIME media types instead of generic media types such as application/json. It is these media types that are going to be versioned instead of the URIs.

- Comments

- Leave a Comment

- Contact Us

If you need more info, please speak with us by using the contact details provided below, or by filling in the contact form.

Our Location

71-75 Shelton Street, London, GB

- Write to us

Success! Your message has been sent to us.
Error! There was an error sending your message.