Versioning APIs using the URI

Clearly segment different versions of the API.

Including the version number in the API's base URI is the most common way to version an API.

An examle base URI might look like:

https://api.example.com/v1

Since API clients already define the API's base URI, including an extra path segment to indicate the API's version does not require any additional effort.

For REST APIs, including the version in the resource's identity violates REST principles. However, often this is the right trade-off to make for the sake of developer ergonomics.

Pros

No additional effort for developers to specify the version, since they already are specifying the base URI.
Implicitly mandatory, clients will not automatically update to a newer version.

Cons

Difficult to evolve the API incrementally since the version number applies to the API as a whole.
Typically a /v2 API is not interoperable with a /v1 API, meaning developers must migrate their entire integration at once.
Incrementing the version number effectively doubles the number of endpoints to support.

OpenAPI reference

This OpenAPI document descibes an API that is versioned by the base URI. Note that the version prefix is included in the Server Object rather than the Paths object.

{
  "openapi": "3.1.0",
  "info": {
    "title": "URI Versioning API",
    "version": "2.1.7"
  },
  "servers": [
    {
      "url": "https://api.example.com/v2",
      "description": "Production API"
    },
    {
      "url": "https://sandbox-api.example.com/v2",
      "description": "Sandbox API"
    }
  ],
  "paths": {
    "/items/{item}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ExampleAPIVersion"
        }
      ],
      "get": {
        "summary": "The item"
      }
    }
  },
  "components": {
    "parameters": {
      "ItemID": {
        "name": "item",
        "in": "path",
        "description": "The unique ID of the item.",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    }
  }
}

Alternative design patterns

Header versioning

Enable versioning on a per-request basis.