Skip to main content
Redhat Developers  Logo
  • Products

    Platforms

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat AI
      Red Hat AI
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • View All Red Hat Products

    Featured

    • Red Hat build of OpenJDK
    • Red Hat Developer Hub
    • Red Hat JBoss Enterprise Application Platform
    • Red Hat OpenShift Dev Spaces
    • Red Hat OpenShift Local
    • Red Hat 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
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Secure Development & Architectures

      • Security
      • Secure coding
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud 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

    • Product Documentation
    • API Catalog
    • Legacy Documentation
  • 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

    • A deep dive into Apache Kafka's KRaft protocol

    • Staying ahead of artificial intelligence threats

    • Strengthen privacy and security with encrypted DNS in RHEL

    • How to enable Ansible Lightspeed intelligent assistant

    • Why some agentic AI developers are moving code from Python to Rust

    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