API Versioning

URL Prefixing

There are many ways to do API versioning. Flask-Rebar encourages a simple and very common approach - URL prefixing.

from flask import Flask
from flask_rebar import Rebar


rebar = Rebar()
v1_registry = rebar.create_handler_registry(prefix='/v1')
v2_registry = rebar.create_handler_registry(prefix='/v2')

@v1_registry.handles(rule='/foos')
@v2_registry.handles(rule='/foos')
def get_foos():
    ...

@v1_registry.handles(rule='/bar')
def get_bars():
    ...

@v2_registry.handles(rule='/bar')
def get_bars():
    ...

app = Flask(__name__)
rebar.init_app(app)

Here we have two registries, and both get registered when calling rebar.init_app.

The same handler function can be used for multiple registries.

This will produce a separate Swagger specification and UI instance per API version, which Flask-Rebar encourages for better support with tools like swagger-codegen.

Cloning a Registry

While its recommended to start versioning an API from the get go, sometimes we don’t. In that case, it’s a common practice to assume that no version prefix is the same as version 1 of the API in order to maintain backwards compatibility for clients that might already be calling non-prefixed endpoints.

Flask-Rebar supports copying an entire registry and changing the URL prefix:

from flask import Flask
from flask_rebar import Rebar


rebar = Rebar()
registry = rebar.create_handler_registry()

@registry.handles(rule='/foos')
def get_foos():
    ...

v1_registry = registry.clone()
v1_registry.prefix = '/v1'
rebar.add_handler_registry(v1_registry)

app = Flask(__name__)
rebar.init_app(app)