How to Support Multiple API Versions in Flask: URL Path Versioning Implementation Guide

APIs are the backbone of modern software, enabling communication between clients (web apps, mobile apps, third-party services) and servers. As your application evolves, you’ll often need to update your API—whether to add features, fix bugs, or improve performance. However, changing an API can break existing clients that rely on older versions. API versioning solves this problem by allowing multiple API versions to coexist, ensuring backward compatibility while enabling innovation.

Among the various API versioning strategies (URL path, query parameters, headers, content negotiation), URL path versioning is the most straightforward and widely adopted. It embeds the version directly in the URL (e.g., /api/v1/users or /api/v2/users), making it easy for clients and developers to identify and use specific versions.

In this guide, we’ll walk through implementing URL path versioning in a Flask application. We’ll cover project structure, blueprint usage, shared code management, testing, and advanced topics like documentation and deprecation. By the end, you’ll have a scalable setup to support multiple API versions seamlessly.

Table of Contents#

  1. What is URL Path Versioning?
  2. Prerequisites
  3. Step-by-Step Implementation
  4. Testing Your Versioned API
  5. Advanced Considerations
  6. Best Practices
  7. Conclusion
  8. References

What is URL Path Versioning?#

URL path versioning is a strategy where the API version is explicitly included in the URL path. For example:

  • https://yourapp.com/api/v1/users (Version 1)
  • https://yourapp.com/api/v2/users (Version 2)

This approach is popular because:

  • Clarity: The version is visible in the URL, making it easy to debug and understand.
  • Simplicity: Clients can switch versions by modifying the URL (no complex header/query logic).
  • Caching: Proxies and CDNs can cache responses by versioned URL, improving performance.

It’s ideal for public APIs or cases where clients need explicit control over the version they use.

Prerequisites#

Before starting, ensure you have:

  • Python 3.8+ installed.
  • Basic familiarity with Flask and Python.
  • pip (Python package manager) for installing dependencies.

Install Flask using:

pip install flask

Step-by-Step Implementation#

Project Structure#

A well-organized project structure is critical for maintaining multiple API versions. We’ll use a modular setup with separate directories for each version and shared code. Here’s the recommended structure:

your_flask_api/  
├── app/  
│   ├── __init__.py          # Flask app initialization  
│   ├── common/              # Shared code (models, utilities)  
│   │   ├── __init__.py  
│   │   └── models.py        # e.g., User model  
│   ├── v1/                  # Version 1 API  
│   │   ├── __init__.py  
│   │   └── routes.py        # V1 routes/blueprints  
│   └── v2/                  # Version 2 API  
│       ├── __init__.py  
│       └── routes.py        # V2 routes/blueprints  
├── config.py                # App configuration  
└── run.py                   # Entry point to run the app

Setting Up the Flask App#

First, initialize the Flask app in app/__init__.py. This file will import and register blueprints for each API version (we’ll create blueprints next).

# app/__init__.py  
from flask import Flask  
from app.v1.routes import v1_bp  
from app.v2.routes import v2_bp  
 
def create_app():  
    app = Flask(__name__)  
 
    # Register blueprints for each version  
    app.register_blueprint(v1_bp, url_prefix='/api/v1')  
    app.register_blueprint(v2_bp, url_prefix='/api/v2')  
 
    return app

Creating Versioned Blueprints#

Flask blueprints are modular components that let you organize routes, templates, and static files. We’ll use blueprints to isolate version-specific logic.

Version 1 Blueprint (app/v1/routes.py)#

Create a blueprint for v1 and define a sample route (e.g., a /users endpoint):

# app/v1/routes.py  
from flask import Blueprint, jsonify  
from app.common.models import get_users  # Shared function  
 
# Initialize blueprint for v1  
v1_bp = Blueprint('v1', __name__)  
 
@v1_bp.route('/users', methods=['GET'])  
def get_users_v1():  
    """Return a list of users (Version 1)."""  
    users = get_users()  # Reuse shared logic  
    # V1 returns minimal user data  
    return jsonify({  
        "version": "v1",  
        "users": [{"id": user["id"], "name": user["name"]} for user in users]  
    }), 200

Version 2 Blueprint (app/v2/routes.py)#

For v2, we’ll extend the /users endpoint to return more details (e.g., email and join date) to demonstrate version differences:

# app/v2/routes.py  
from flask import Blueprint, jsonify  
from app.common.models import get_users  # Reuse shared logic  
 
# Initialize blueprint for v2  
v2_bp = Blueprint('v2', __name__)  
 
@v2_bp.route('/users', methods=['GET'])  
def get_users_v2():  
    """Return a list of users with extra details (Version 2)."""  
    users = get_users()  
    # V2 returns detailed user data  
    return jsonify({  
        "version": "v2",  
        "users": [  
            {  
                "id": user["id"],  
                "name": user["name"],  
                "email": user["email"],  
                "join_date": user["join_date"]  
            } for user in users  
        ]  
    }), 200

Registering Blueprints with Versioned Paths#

In app/__init__.py, we already registered the blueprints with url_prefix='/api/v1' and url_prefix='/api/v2'. This ensures:

  • All routes in v1_bp are prefixed with /api/v1 (e.g., /api/v1/users).
  • All routes in v2_bp are prefixed with /api/v2 (e.g., /api/v2/users).

Implementing Version-Specific Routes#

Each version’s routes are defined in their respective routes.py files. The key is to isolate breaking changes between versions. For example:

  • V1 might return a simple JSON structure.
  • V2 could return nested data, new fields, or a different response format.

In our example, v2 adds email and join_date to user objects—this is a non-breaking change for v1 clients, as they can ignore new fields.

Sharing Code Between Versions#

To avoid duplication, store shared logic (e.g., database models, utility functions) in the app/common/ directory.

Example: Shared User Data (app/common/models.py)#

Create a mock function to simulate fetching user data (replace with a real database call in production):

# app/common/models.py  
def get_users():  
    """Shared function to fetch user data (simulated)."""  
    return [  
        {  
            "id": 1,  
            "name": "Alice",  
            "email": "[email protected]",  
            "join_date": "2023-01-15"  
        },  
        {  
            "id": 2,  
            "name": "Bob",  
            "email": "[email protected]",  
            "join_date": "2023-02-20"  
        }  
    ]

Both v1 and v2 import get_users from app.common.models, ensuring consistency in data retrieval.

Testing Your Versioned API#

Now, let’s test the API. Create an entry point run.py to start the app:

# run.py  
from app import create_app  
 
app = create_app()  
 
if __name__ == '__main__':  
    app.run(debug=True)  # Use debug=False in production

Run the App#

Start the server:

python run.py

Test with curl or Postman#

Test Version 1#

curl http://localhost:5000/api/v1/users

Expected Response (v1):

{  
  "version": "v1",  
  "users": [  
    {"id": 1, "name": "Alice"},  
    {"id": 2, "name": "Bob"}  
  ]  
}

Test Version 2#

curl http://localhost:5000/api/v2/users

Expected Response (v2):

{  
  "version": "v2",  
  "users": [  
    {  
      "id": 1,  
      "name": "Alice",  
      "email": "[email protected]",  
      "join_date": "2023-01-15"  
    },  
    {  
      "id": 2,  
      "name": "Bob",  
      "email": "[email protected]",  
      "join_date": "2023-02-20"  
    }  
  ]  
}

Both versions work independently—success!

Advanced Considerations#

API Documentation for Multiple Versions#

Clients need clear documentation for each API version. Use tools like Flask-RESTX (a fork of Flask-RESTPlus) to auto-generate Swagger/OpenAPI docs for each version.

Step 1: Install Flask-RESTX:

pip install flask-restx

Step 2: Update v1 and v2 blueprints to use Flask-RESTX namespaces (for documentation):

# app/v1/routes.py (updated with Flask-RESTX)  
from flask_restx import Api, Resource, fields  
from flask import Blueprint  
from app.common.models import get_users  
 
v1_bp = Blueprint('v1', __name__)  
v1_api = Api(v1_bp, version='1.0', title='API v1', description='Version 1 of the User API')  
 
# Define a data model for documentation  
user_model_v1 = v1_api.model('UserV1', {  
    'id': fields.Integer(description='User ID'),  
    'name': fields.String(description='User Name')  
})  
 
@v1_api.route('/users')  
class UsersV1(Resource):  
    @v1_api.marshal_list_with(user_model_v1)  
    def get(self):  
        """Get all users (Version 1)"""  
        return get_users()

Repeat for v2 with a user_model_v2 including email and join_date.

Step 3: Access Docs
Visit http://localhost:5000/api/v1 or http://localhost:5000/api/v2 in your browser to see interactive Swagger docs for each version.

Deprecating Old Versions#

When retiring a version (e.g., v1), notify clients gracefully:

  1. Add Deprecation Headers: Include a Deprecation header in responses:

    @v1_bp.route('/users', methods=['GET'])  
def get_users_v1():  
    response = jsonify(...)  
    response.headers['Deprecation'] = 'This version (v1) will be sunset on 2024-01-01. Migrate to v2.'  
    return response

  2. Return Warnings in Responses: Add a warning field to the JSON body:

    {  
  "version": "v1",  
  "warning": "v1 is deprecated. Use v2 instead.",  
  "users": [...]  
}

Handling Unknown Versions#

If a client requests a non-existent version (e.g., /api/v3/users), return a 404 Not Found error with a helpful message. Add a catch-all route in app/__init__.py:

# app/__init__.py (add after registering blueprints)  
from flask import jsonify  
 
@app.errorhandler(404)  
def version_not_found(e):  
    return jsonify({  
        "error": "API version not found",  
        "message": "Valid versions: v1, v2"  
    }), 404

Best Practices#

  1. Limit Versions: Avoid maintaining too many versions (e.g., only support the latest + 1 previous version).
  2. Semantic Versioning: Use v1, v2 (not v1.1.0) for simplicity—reserve minor/patch versions for non-breaking changes within a major version.
  3. Isolate Logic: Keep version-specific code in versioned directories; reuse shared code via common/.
  4. Test Rigorously: Write unit/integration tests for each version to prevent regressions.
  5. Communicate Changes: Document version differences (e.g., new fields, removed endpoints) in release notes.

Conclusion#

URL path versioning is a robust way to support multiple API versions in Flask. By using blueprints, modular project structures, and shared code, you can scale your API while keeping it maintainable. Remember to document versions, deprecate gracefully, and test rigorously to ensure a smooth experience for clients.

With this setup, you’re ready to evolve your API without breaking existing users!

References#

2026-02