Mastering RESTful API Versioning: Strategies, Practices, and Routing

1. Introduction

Software iteration forces developers to consider API version control because not all users adopt the latest software and business requirements change frequently. Ensuring backward compatibility when releasing new versions requires a solid API versioning strategy.

2. API Version Control

Effective RESTful API versioning is closely tied to business needs, yet many product managers overlook it, leading to unstable releases that can damage brand image and user experience.

Major Version Consistency Strategy

When business changes break existing clients and cannot be compatible, the release should be treated as a major version; otherwise, a minor version is sufficient.

Clients should verify their major version against the server's; if they differ, users can be prompted to upgrade. This simple, strict approach may not suit all scenarios, especially when multiple client versions must run concurrently.

Parallel Multi‑Version Support

Parallel versions require clients to include a version identifier in requests, commonly using the following methods.

Version in URI

Prefix all URIs with the version, e.g.,

/api/v1

, where

1

is the iteratable version number.

Version in Host

Specify the version in the host name, such as

https://v1.myapi.com

or

https://v2.myapi.com

, each pointing to a different version.

Version in Header

To avoid version explosion in URLs, set the version in the request header, for example:

<code>POST /foo/upload HTTP/1.1
Host: localhost:8080
Api-Version: v1
Content-Type: application/json

{
    "name": "felord",
    "age": 18
}
</code>

<code>POST /foo/upload HTTP/1.1
Host: localhost:8080
Api-Version: v2
Content-Type: application/json

{
    "name": "felord",
    "age": 18,
    "gender" 1
}
</code>

By adding the

Api-Version

header, the desired API version is explicitly indicated.

3. Routing Strategies

When multiple versions coexist, routing becomes a challenge and must align with the deployment model. For a single application supporting multiple versions, filters or interceptors can handle routing, while URI versioning already scopes routing to the interface level, making it suitable for small to medium projects.

If version v1 runs on server A and version v2 on server B, a gateway or proxy can route requests based on the version header. An Nginx example:

<code>upstream v1 {
    server 127.0.0.1:8081;
}
upstream v2 {
    server 127.0.0.1:8082;
}

server {
    listen 8080;
    server_name localhost;
    charset utf-8;
    location / {
        set $not_match 0;
        # Route based on Api-Version
        if ($http_app_version = "v1") {
            proxy_pass http://v1;
            set $not_match 1;
        }

        if ($http_app_version = "v2") {
            proxy_pass http://v2;
            set $not_match 1;
        }

        if($not_match = 0){
            # handle no match
        }
    }
}
</code>

Host‑ and URI‑based routing can be implemented in a similar fashion.