• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar
  • Skip to footer

REST API Tutorial

  • REST
  • JSON
  • Dark Mode
Home / REST / REST API Versioning

REST API Versioning

To manage this complexity, version your API. Versioning helps you iterate faster when the needed changes are identified.

Change in an API is inevitable as your knowledge and experience of a system improve. Managing the impact of this change can be quite a challenge when it threatens to break existing client integration.

When to Version

APIs only need to be up-versioned when a breaking change is made. Breaking changes include:

  • a change in the format of the response data for one or more calls
  • a change in the request or response type (i.e. changing an integer to a float)
  • removing any part of the API.

Breaking changes should always result in a change to the major version number for an API or content response type.

Non-breaking changes, such as adding new endpoints or new response parameters, do not require a change to the major version number. However, it can be helpful to track the minor versions of APIs when changes are made to support customers who may be receiving cached versions of data or may be experiencing other API issues.

How to Version

REST doesn’t provide for any specific versioning guidelines but the more commonly used approaches fall into three categories:

URI Versioning

Using the URI is the most straightforward approach (and most commonly used as well) though it does violate the principle that a URI should refer to a unique resource. You are also guaranteed to break client integration when a version is updated.

e.g.

http://api.example.com/v1
http://apiv1.example.com

The version need not be numeric, nor specified using the “v[x]” syntax. Alternatives include dates, project names, seasons or other identifiers that are meaningful enough to the team producing the APIs and flexible enough to change as the versions change.

Versioning using Custom Request Header

A custom header (e.g. Accept-version) allows you to preserve your URIs between versions though it is effectively a duplicate of the content negotiation behavior implemented by the existing Accept header.

e.g.

Accept-version: v1
Accept-version: v2

Versioning using Accept header

Content negotiation may let you preserve a clean set of URLs but you still have to deal with the complexity of serving different versions of content somewhere. This burden tends to be moved up the stack to your API controllers which become responsible for figuring out which version of a resource to send. The end result tends to be a more complex API as clients have to know which headers to specify before requesting a resource.

e.g.

Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0

In the real world, an API is never going to be completely stable. So it’s important how this change is managed. A well documented and gradual deprecation of API can be an acceptable practice for most of the APIs.

Was this article helpful?

TwitterFacebookLinkedInReddit
Previous Tutorial:
REST Architectural Constraints
Next Tutorial:
REST Resource Naming Guide

Reader Interactions

Comments

  1. Charles says

    October 13, 2020 at 12:53 am

    This should apply to the Requests as well not just the Responses.

    Reply
    • Admin says

      October 13, 2020 at 7:59 am

      Yes. True.

      Reply
  2. Shri says

    January 18, 2020 at 9:02 am

    Do you deploy various versions as single service Or it should be two separate services running in different pods

    Reply
  3. Mark says

    January 25, 2019 at 11:55 pm

    A third option would be to include a version key:value hint in the JSON body.

    Reply
    • Dennis says

      March 1, 2019 at 10:43 am

      That won’t be of much use with GET.

      Reply

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Primary Sidebar

Search Tutorials

Learn REST

  • What is REST?
  • REST Constraints
  • REST Resource Naming Guide

Guides

  • Caching
  • Compression
  • Content Negotiation
  • HATEOAS
  • Idempotence
  • Security Essentials
  • Versioning
  • Statelessness in REST APIs

Tech – How To

  • REST API Design Tutorial
  • Create REST APIs with JAX-RS

FAQs

  • PUT vs POST
  • N+1 Problem
  • ‘q’ Parameter

Resources

  • What is an API?
  • Comparing SOAP vs REST APIs
  • HTTP Methods
  • Richardson Maturity Model
  • HTTP Response Codes
    • 200 (OK)
    • 201 (Created)
    • 202 (Accepted)
    • 204 (No Content)
    • 301 (Moved Permanently)

Footer

References

  • The dissertation by Roy Thomas Fielding
  • Uniform Resource Identifier (URI, URL, URN) [RFC 3986]
  • Internet MediaTypes
  • Web Application Description Language (WADL)

Meta Links

  • About
  • Contact Us
  • Privacy Policy

Blogs

  • How To Do In Java

Copyright © 2020 · restfulapi.net · All Rights Reserved. | Sitemap