Restful Versioning

title: "RESTful Versioning — Managing API Versions in REST" description: "RESTful versioning manages API evolution through URI prefixes or content negotiation headers to provide backward-compatible changes without breaking clients." date: 2026-06-28 lastmod: 2026-06-28 weight: 19 tags: [apis, restful] }

RESTful versioning allows APIs to evolve by maintaining multiple versions through URI path prefixes or content negotiation, ensuring existing clients continue working.

What You'll Learn

• URI versioning for REST
• Header-based versioning
• Version deprecation in REST

Why It Matters

Versioning is essential for REST API evolution. Without it, you can't make breaking changes without breaking existing clients.

Code Examples

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

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

# Shared logic with version parameter
@app.route('/v<version>/products')
def list_products(version):
    if version == '1':
        return jsonify([p.basic() for p in products])
    elif version == '2':
        return jsonify([p.detail() for p in products])
    else:
        return jsonify({"error": "Unsupported version"}), 400

# Deprecation headers for old versions
@app.after_request
def version_deprecation(response):
    if request.path.startswith('/v1/'):
        response.headers['Deprecation'] = 'true'
        response.headers['Sunset'] = 'Sat, 31 Dec 2026 23:59:59 GMT'
        response.headers['Link'] = '</v2/users>; rel="successor-version"'
    return response

// Express version routing
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);

Common Mistakes

1. No Default Version

Returning 404 when no version is specified.

2. Breaking Changes Without New Version

Changing v1 behavior instead of creating v2.

3. Supporting Too Many Versions

More than 2-3 versions creates maintenance burden.

4. No Deprecation Policy

Clients don't know when old versions will be removed.

5. Inconsistent Version Application

Some endpoints versioned, others not.

Practice Questions

1. What is the most common REST versioning approach?
2. How many versions should you support?
3. What headers indicate a deprecated version?
4. How do you route versions in code?
5. When should you create a new version?

Answers:

1. URI path versioning (/v1/users).
2. 2-3 at most.
3. Deprecation, Sunset, and Link headers.
4. Using separate routers or blueprints per version.
5. When making backward-incompatible changes.

Challenge: Implement versioning for a REST API with version-specific blueprints and deprecation headers for old versions.

FAQ