Uri Versioning

title: "URI Versioning — /v1/ and /v2/ Path Prefixes for API Versioning" description: "URI versioning embeds the version number in the URL path like /v1/users and /v2/users, making versions explicit, cacheable, and easy to route." date: 2026-06-28 lastmod: 2026-06-28 weight: 13 tags: [apis, versioning] }

URI versioning places the version identifier in the URL path (e.g., /v1/users), making it immediately visible to developers and straightforward to implement.

What You'll Learn

• URI versioning implementation
• Pros and cons of URI versioning
• Routing multiple versions

Why It Matters

URI versioning is the most common and simplest versioning strategy. Major APIs like Stripe, Twilio, and SendGrid use it.

Code Examples

# Flask URI versioning
from flask import Blueprint

v1 = Blueprint('v1', __name__)
v2 = Blueprint('v2', __name__)

@v1.route('/users')
def list_users_v1():
    return jsonify([{"id": u.id, "name": u.name} for u in users])

@v2.route('/users')
def list_users_v2():
    return jsonify([{"id": u.id, "name": u.name, "email": u.email} for u in users])

# Register with version prefix
app.register_blueprint(v1, url_prefix='/v1')
app.register_blueprint(v2, url_prefix='/v2')

# Or with URL parameter
@app.route('/v<int:version>/users')
def versioned_users(version):
    if version == 1:
        return jsonify(v1_format())
    elif version == 2:
        return jsonify(v2_format())
    else:
        return jsonify({"error": "Unsupported version"}), 400

// Express URI versioning
const v1Router = express.Router();
const v2Router = express.Router();

v1Router.get('/users', (req, res) => {
  res.json(users.map(u => ({ id: u.id, name: u.name })));
});

v2Router.get('/users', (req, res) => {
  res.json(users.map(u => ({ id: u.id, name: u.name, email: u.email })));
});

app.use('/v1', v1Router);
app.use('/v2', v2Router);

# Nginx routing by version
server {
    location /v1/ {
        proxy_pass http://app-v1:3000;
    }
    location /v2/ {
        proxy_pass http://app-v2:3000;
    }
}

Common Mistakes

1. Inconsistent Version Prefix

Some endpoints /v1/users, others /api/v2/users. Standardize.

2. No Default Version

Return the latest version or error when no version is specified.

3. Version in Resource ID

/v1/users/123/v1/orders — version should be at the root.

4. URL Parameter Not Version

Using /v1 vs /v2 implies minor versions too. Use major versions only.

5. Not Routing at Infrastructure Level

Use API gateway or reverse proxy for version routing.

Practice Questions

1. What does a URI-versioned URL look like?
2. What is the main advantage of URI versioning?
3. What is the main disadvantage?
4. Which major APIs use URI versioning?
5. How do you route versions at the infrastructure level?

Answers:

1. /v1/users, /v2/users, etc.
2. Explicit and visible. Developers can see the version instantly.
3. URL pollution and less RESTful (resource URL changes with version).
4. Stripe, Twilio, SendGrid, and many others.
5. With Nginx, API gateway, or load balancer routing rules.

Challenge: Implement URI versioning for a REST API with two versions. Deploy them on separate subdomains or routes.

FAQ