Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

API versioning methods: A brief reference

June 13, 2016
Hugo Guerrero Vanessa Ramos
Related topics:
APIs
Related products:
Developer Tools

Share:

    This article lists the most common methods in use to version your API. Its intention is not to convince you to use one or another but rather to provide a comprehensive list of the methodologies used, together with some of their advantages and disadvantages and some additional references for each method as well.

    Advantages and disadvantages

    Media type versioning


    Also known as “content negotiation” or “accept header”

    You customize the accept media type header to specify the version:

    Accept: application/vnd.myapi.v2+json or Accept: Application/vnd.api.article+xml; version=1.0

    PROS

    • You can version directly at the resource level (preserve your URIs between versions).
    • This is the closest to the original RESTful specification (check the references below).

    CONS

    • Harder to test as the versions are not shown on the URL.
    • You will need something else than just a browser (i.e., developer tools) to explore the different versions.
    • They distort the HTTP headers’ purpose: clients will need to know the media type for each resource and request the same one throughout their use of your API to ensure their code continues to function normally as you push out new changes.

    (Custom) headers versioning


    One of the most (mis)used methods (i.e., X-API-Version: 2)

    PROS

    • Preserve your URIs between versions (because you do not add any version information to the URI).
    • Neater method than the URI versioning up next.

    CONS

    • If you are already versioning resources with this technique, versioning the API as well can lead to a hard-to-manage configuration.

    URI versioning


    You will use a different path for different versions of the API endpoints (i.e., api.example.com/v1/resource)

    PROS

    • Most common method currently in use by APIs today.
    • It allows exploring different versions with just a browser. (Enables visual identification of the version being requested).
    • It’s easy to use!

    CONS

    • It disrupts the RESTful compliance: URIs should represent resources and not versions (one URI = one resource/resource version).
    • Just like the previous method you should try to avoid this method if you are also versioning resources.

    Domain versioning (a.k.a. “hostname versioning”)


    It’s a particular case of the URI versioning in the previous section, and it shares its pros and cons (i.e., apiv1.example.com/resource).

    PROS

    • Same as in URI versioning.
    • Also easily route it to a completely different server.
    • Could be interesting if you really want to write something very different for the same resources.

    CONS

    • Same as in URI versioning, plus users may have to change their security settings to be able to make calls to this new version.

    (Request) parameter versioning


    Use a parameter in the request to provide the API version being used (i.e., GET /something/?version=0.1 HTTP/1.1).

    PROS

    • This is mostly indicated for JavaScript API (CORS enabled APIs).
    • Just like the URI versioning allows visual identification.
    • Can be optional (if no parameter is specified, the last version will be provided).

    CONS

    • If you mix resource versions with this type of API versioning, it can get very messy.

    Date versioning (a.k.a. “point-in-time versioning”, “dynamic date versioning”)


    The first time a user makes a request to the API, that point-in-time (timestamp) gets saved alongside the account data and becomes their version until they choose to manually bump it to the current version.

    PROS

    • Allows shipping new API features without changing an endpoint.
    • Being able to easily see which customers are using which versions of the API.

    CONS

    • It’s a bit complex to implement.
    • Makes traceability of what has changed more difficult (It can be confusing to understand whether the timestamp is compilation time or the timestamp when the API was released).

    Popularity

    Another table that I thought might be interesting to share with you is this one below, with the estimated popularity – how often that method is used: high, medium and low usage frequencies – and some references for you to check out. The popularity is based on the listings of some popular REST APIs (you can find some of these listings on the next section of the post).

    Media type versioning (a.k.a “content negotiation” or “accept header”)


    Popularity: MEDIUM

    References:

    • GitHub has gone down this path.
    • https://www.rfc-editor.org/rfc/rfc4288
    • http://www.narwhl.com/2015/03/the-ultimate-solution-to-versioning-rest-apis-content-negotiation/
    • http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_2
    • http://www.narwhl.com/2015/03/the-ultimate-solution-to-versioning-rest-apis-content-negotiation/
    • Foursquare: https://developer.foursquare.com/reference/versioning

    (Custom) headers versioning


    Popularity: MEDIUM

    References:

    Microsoft uses this method: https://msdn.microsoft.com/en-us/library/azure/dd894041.aspx

    URI versioning


    Popularity: HIGH

    References:

    • Segment uses this approach: https://segment.com/docs/libraries/http/
    • And Twitter too: https://blog.twitter.com/developer/en_us/a/2013/api-v1-retirement-final-dates

    Domain versioning (a.k.a. “hostname versioning”)


    Popularity: LOW

    References:

    Facebook uses this method: https://developers.facebook.com/docs/marketing-api/versions

    (Request) parameter versioning


    Popularity: HIGH

    References:

    Pivotal uses this: https://blog.pivotal.io/labs/labs/api-versioning

    Date versioning (a.k.a. “point-in-time versioning”, “dynamic date versioning”)


    Popularity: LOW

    References:

    • Clearbit (https://clearbit.com/docs#versioning),
    • Runscope (http://blog.runscope.com/posts/managing-change-behind-the-scenes-with-continuous-regression-testing-for-a-seamless-customer-experience)
    • And Twilio use this method.

    References

    Finally, let's wrap up with some generic, but equally interesting, references on the subject matter:

    • https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown
    • http://urthen.github.io/2013/05/09/ways-to-version-your-api/
    • http://stackoverflow.com/questions/389169/best-practices-for-api-versioning
    • http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/
    Last updated: June 13, 2024

    Recent Posts

    • AI meets containers: My first step into Podman AI Lab

    • Live migrating VMs with OpenShift Virtualization

    • Storage considerations for OpenShift Virtualization

    • Upgrade from OpenShift Service Mesh 2.6 to 3.0 with Kiali

    • EE Builder with Ansible Automation Platform on OpenShift

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit
    © 2025 Red Hat

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue