Gartner Research

Choosing the Right Web API Versioning Model

Published: 01 October 2014

ID: G00269144

Analyst(s): Gary Olliffe


Change is inevitable, and managing changes in your Web APIs is critical to their success. API architects and designers must learn how to evolve APIs to provide stability to consumers, as well as understand the options when needing to create new versions of their APIs, resources and representations.

Table Of Contents



  • Breaking Changes Are a Last Resort
  • Learn From Others' Experience
  • The Criteria
    • Versioning Scope
    • API Implementation
    • API Consumption
  • The Versioning Models
    • API Evolution
    • Root Namespace URI Versioning
    • Resource-Level URI Versioning
    • HTTP Content Header Versioning
    • HTTP Query Parameter Versioning


The Details

  • Other Versioning Models
    • API Version in the Domain/Subdomain Name
    • API Version as a Resource "Extension"
    • Including "Date of Client Implementation" as Part of the URI Path
    • Including "Date of Client Implementation" as a Query Parameter
    • Use of "vlatest" (or Equivalent) as an Explicit Identifier for Latest Version
    • Content Negotiation With Custom Headers
    • Payload Versioning

Gartner Recommended Reading

©2022 Gartner, Inc. and/or its affiliates. All rights reserved. Gartner is a registered trademark of Gartner, Inc. and its affiliates. This publication may not be reproduced or distributed in any form without Gartner’s prior written permission. It consists of the opinions of Gartner’s research organization, which should not be construed as statements of fact. While the information contained in this publication has been obtained from sources believed to be reliable, Gartner disclaims all warranties as to the accuracy, completeness or adequacy of such information. Although Gartner research may address legal and financial issues, Gartner does not provide legal or investment advice and its research should not be construed or used as such. Your access and use of this publication are governed by Gartner’s Usage Policy. Gartner prides itself on its reputation for independence and objectivity. Its research is produced independently by its research organization without input or influence from any third party. For further information, see Guiding Principles on Independence and Objectivity.

Already have a Gartner Account?

Become a client

Learn how to access this content as a Gartner client.