API versioning with blueprints in Flask - Mini Project: Build & Apply

API Versioning with Blueprints in Flask

📖 Scenario: You are building a simple web API for a bookstore. You want to support two versions of the API so clients can choose which version to use. You will use Flask blueprints to organize the code for each API version.

🎯 Goal: Create two Flask blueprints named v1 and v2 for API version 1 and version 2. Each blueprint will have a route /books that returns a JSON list of books. Then register both blueprints in the Flask app with URL prefixes /api/v1 and /api/v2.

📋 What You'll Learn

Create a Flask app instance named app

Create a blueprint named v1 with a route /books returning a JSON list of book titles for version 1

Create a blueprint named v2 with a route /books returning a JSON list of book titles for version 2

Register both blueprints on the Flask app with URL prefixes /api/v1 and /api/v2

💡 Why This Matters

🌍 Real World

API versioning is important when you want to improve or change your API without breaking existing clients. Blueprints help organize code for each version cleanly.

💼 Career

Many web developers and backend engineers use Flask blueprints to build scalable APIs that support multiple versions for different clients.

1

Create the Flask app and version 1 blueprint

Create a Flask app instance called app. Then create a blueprint called v1 with the name 'v1' and import name __name__. Add a route /books to v1 that returns a JSON list ["The Great Gatsby", "1984"].

Flask

# Create Flask app instance called app
# Create blueprint v1 with name 'v1' and __name__
# Add route /books to v1 returning JSON list ["The Great Gatsby", "1984"]

Hint

Use Flask(__name__) to create the app. Use Blueprint('v1', __name__) to create the blueprint. Use @v1.route('/books') to add the route. Return the JSON list with jsonify.

2

Create the version 2 blueprint with updated book list

Create a blueprint called v2 with the name 'v2' and import name __name__. Add a route /books to v2 that returns a JSON list ["Brave New World", "Fahrenheit 451"].

Flask

from flask import Flask, Blueprint, jsonify

app = Flask(__name__)

v1 = Blueprint('v1', __name__)

@v1.route('/books')
def books_v1():
    return jsonify(["The Great Gatsby", "1984"])

# Create blueprint v2 with name 'v2' and __name__
# Add route /books to v2 returning JSON list ["Brave New World", "Fahrenheit 451"]

Hint

Create the v2 blueprint like v1. Add the /books route returning the new list of books using jsonify.

3

Register blueprints with URL prefixes

Register the blueprint v1 on the Flask app app with the URL prefix /api/v1. Register the blueprint v2 on app with the URL prefix /api/v2.

Flask

from flask import Flask, Blueprint, jsonify

app = Flask(__name__)

v1 = Blueprint('v1', __name__)

@v1.route('/books')
def books_v1():
    return jsonify(["The Great Gatsby", "1984"])

v2 = Blueprint('v2', __name__)

@v2.route('/books')
def books_v2():
    return jsonify(["Brave New World", "Fahrenheit 451"])

# Register v1 blueprint with prefix /api/v1
# Register v2 blueprint with prefix /api/v2

Hint

Use app.register_blueprint() with the url_prefix argument to register each blueprint.

4

Add app run block for local testing

Add the standard Flask app run block at the bottom: if __name__ == '__main__': then run app.run(debug=True).

Flask

from flask import Flask, Blueprint, jsonify

app = Flask(__name__)

v1 = Blueprint('v1', __name__)

@v1.route('/books')
def books_v1():
    return jsonify(["The Great Gatsby", "1984"])

v2 = Blueprint('v2', __name__)

@v2.route('/books')
def books_v2():
    return jsonify(["Brave New World", "Fahrenheit 451"])

app.register_blueprint(v1, url_prefix='/api/v1')
app.register_blueprint(v2, url_prefix='/api/v2')

# Add app run block here

Hint

Add the standard Flask run block to start the server locally with debugging enabled.

Practice

1. What is the main purpose of using Blueprints for API versioning in Flask?

easy

A. To store user session data securely

B. To speed up the Flask server automatically

C. To organize different API versions with separate URL prefixes

D. To create database models for each API version

Solution

1. Step 1: Understand Blueprints role in Flask

   Blueprints allow grouping routes and related code logically.

2. Step 2: Connect Blueprints to API versioning

   Using url_prefix in Blueprints lets you separate API versions by URL path.

3. Final Answer:

   To organize different API versions with separate URL prefixes -> Option C

4. Quick Check:

   Blueprints + url_prefix = versioned APIs [OK]

Hint: Blueprints + url_prefix separate API versions clearly [OK]

Common Mistakes:

• Thinking Blueprints speed up the server
• Confusing Blueprints with session management
• Assuming Blueprints create database models

2. Which of the following is the correct way to create a Blueprint for API version 1 with prefix '/api/v1'?

easy

A. bp = Blueprint('api_v1', __name__, url_prefix='/api/v1')

B. bp = Blueprint('api_v1', url_prefix='/api/v1')

C. bp = Blueprint(__name__, 'api_v1', url_prefix='/api/v1')

D. bp = Blueprint('api_v1', __name__, prefix='/api/v1')

Solution

1. Step 1: Recall Blueprint constructor parameters

   Blueprint(name, import_name, url_prefix=...)

2. Step 2: Identify correct syntax

   bp = Blueprint('api_v1', __name__, url_prefix='/api/v1') uses correct order and url_prefix keyword.

3. Final Answer:

   bp = Blueprint('api_v1', __name__, url_prefix='/api/v1') -> Option A

4. Quick Check:

   Blueprint(name, __name__, url_prefix=...) correct [OK]

Hint: Blueprint needs name, __name__, and url_prefix keyword [OK]

Common Mistakes:

• Omitting __name__ parameter
• Using 'prefix' instead of 'url_prefix'
• Swapping parameter order incorrectly

3. Given this Flask app code, what URL will return 'Hello from v2!'?

from flask import Flask, Blueprint
app = Flask(__name__)

bp_v1 = Blueprint('v1', __name__, url_prefix='/api/v1')
@bp_v1.route('/hello')
def hello_v1():
    return 'Hello from v1!'

bp_v2 = Blueprint('v2', __name__, url_prefix='/api/v2')
@bp_v2.route('/hello')
def hello_v2():
    return 'Hello from v2!'

app.register_blueprint(bp_v1)
app.register_blueprint(bp_v2)

medium

A. /api/v2/hello

B. /hello

C. /v2/hello

D. /api/v1/hello

Solution

1. Step 1: Check Blueprint url_prefix for v2

   Blueprint 'v2' uses url_prefix='/api/v2'.

2. Step 2: Check route path inside v2 Blueprint

   Route is '/hello', so full path is '/api/v2/hello'.

3. Final Answer:

   /api/v2/hello -> Option A

4. Quick Check:

   Blueprint prefix + route = full URL [OK]

Hint: Combine url_prefix and route path for full URL [OK]

Common Mistakes:

• Ignoring url_prefix and using only route path
• Confusing v1 and v2 prefixes
• Assuming route is registered at root '/'

4. What is wrong with this Flask code for versioned API Blueprints?

bp_v1 = Blueprint('v1', __name__, url_prefix='/api/v1')
@bp_v1.route('/data')
def data_v1():
    return 'Data v1'

app.register_blueprint(bp_v1)

bp_v2 = Blueprint('v2', __name__, url_prefix='/api/v2')
@bp_v1.route('/data')
def data_v2():
    return 'Data v2'

app.register_blueprint(bp_v2)

medium

A. Functions cannot return strings directly

B. Blueprints cannot have the same route path

C. url_prefix should be set on app, not Blueprint

D. The second route decorator uses bp_v1 instead of bp_v2

Solution

1. Step 1: Identify route decorators and Blueprints

   The second route uses @bp_v1.route but should use @bp_v2.route.

2. Step 2: Understand impact of wrong decorator

   This causes the second function to register on the first Blueprint, not the second.

3. Final Answer:

   The second route decorator uses bp_v1 instead of bp_v2 -> Option D

4. Quick Check:

   Route decorator must match Blueprint instance [OK]

Hint: Match route decorator to correct Blueprint instance [OK]

Common Mistakes:

• Using wrong Blueprint for route decorator
• Thinking url_prefix belongs on app
• Believing functions can't return strings

5. You want to add a new API version 3 with a Blueprint and share a common route '/status' that returns different messages per version. Which approach correctly implements this in Flask?

hard

A. Define '/status' route only once on app without Blueprints and check version from headers

B. Create separate Blueprints for v1, v2, v3 each with url_prefix and define '/status' route inside each Blueprint

C. Create one Blueprint with url_prefix='/api' and use if-else inside '/status' route to check version

D. Use Flask extensions to automatically version APIs without Blueprints

Solution

1. Step 1: Understand version separation with Blueprints

   Each API version should have its own Blueprint with distinct url_prefix.

2. Step 2: Define '/status' route separately in each Blueprint

   This allows each version to return its own message cleanly and maintainably.

3. Final Answer:

   Create separate Blueprints for v1, v2, v3 each with url_prefix and define '/status' route inside each Blueprint -> Option B

4. Quick Check:

   Separate Blueprints per version = clean versioning [OK]

Hint: Use separate Blueprints per version for clean route separation [OK]

Common Mistakes:

• Trying to handle versions inside one route with if-else
• Defining routes only once without version separation
• Relying on extensions without understanding Blueprints