| + definition + | + ++ example + | + ++ filename + | + ++ extension + | +
|---|---|---|---|
|
+ \ |
+
+ + page.txt + | + +
+ "page"
+ |
+
+
+ "txt"
+ |
+
|
+ \ |
+
+ + cat.jpg + | + +
+ "cat"
+ |
+
+
+ "jpg"
+ |
+
+ \|
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | cat.jpg | |
+ "cat" | "jpg"
+ |
|
+ |
+
+ + 123.txt + | + +
+ 123
+ |
+
+
+ "txt"
+ |
+
+ |
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | 123.svg | |
+ 123 | "svg"
+ |
|
+ |
+
+ + 3.14.tar.gz + | + +
+ 3.14
+ |
+
+
+ "tar.gz"
+ |
+
| + 定義 + | + ++ 例 + | + ++ ファイル名 + | + ++ 拡張子 + | +
|---|---|---|---|
|
+ \ |
+
+ + page.txt + | + +
+ "page"
+ |
+
+
+ "txt"
+ |
+
|
+ \ |
+
+ + cat.jpg + | + +
+ "cat"
+ |
+
+
+ "jpg"
+ |
+
+ \|
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | cat.jpg | |
+ "cat" | "jpg"
+ |
|
+ |
+
+ + 123.txt + | + +
+ 123
+ |
+
+
+ "txt"
+ |
+
+ |
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | 123.svg | |
+ 123 | "svg"
+ |
|
+ |
+
+ + 3.14.tar.gz + | + +
+ 3.14
+ |
+
+
+ "tar.gz"
+ |
+
Hello world!
") +``` +:--- + +## Per Blueprint Group + +---:1 In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint group. The same will be inherited to all the blueprint grouped under it if the blueprints don't already override the same information with a value specified while creating a blueprint instance. + +When using blueprint groups for managing the versions, the following order is followed to apply the Version prefix to the routes being registered. + +1. Route Level configuration +2. Blueprint level configuration +3. Blueprint Group level configuration + +If we find a more pointed versioning specification, we will pick that over the more generic versioning specification provided under the Blueprint or Blueprint Group :--:1 +```python +from sanic.blueprints import Blueprint +from sanic.response import json + +bp1 = Blueprint( + name="blueprint-1", + url_prefix="/bp1", + version=1.25, +) +bp2 = Blueprint( + name="blueprint-2", + url_prefix="/bp2", +) + +group = Blueprint.group( + [bp1, bp2], + url_prefix="/bp-group", + version="v2", +) + +# GET /v1.25/bp-group/bp1/endpoint-1 +@bp1.get("/endpoint-1") +async def handle_endpoint_1_bp1(request): + return json({"Source": "blueprint-1/endpoint-1"}) + +# GET /v2/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-1") +async def handle_endpoint_1_bp2(request): + return json({"Source": "blueprint-2/endpoint-1"}) + +# GET /v1/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-2", version=1) +async def handle_endpoint_2_bp2(request): + return json({"Source": "blueprint-2/endpoint-2"}) +``` +:--- + +## Version prefix + +As seen above, the `version` that is applied to a route is **always** the first segment in the generated URI path. Therefore, to make it possible to add path segments before the version, every place that a `version` argument is passed, you can also pass `version_prefix`. + +The `version_prefix` argument can be defined in: + +- `app.route` and `bp.route` decorators (and all the convenience decorators also) +- `Blueprint` instantiation +- `Blueprint.group` constructor +- `BlueprintGroup` instantiation +- `app.blueprint` registration + +If there are definitions in multiple places, a more specific definition overrides a more general. This list provides that hierarchy. + +The default value of `version_prefix` is `/v`. + +---:1 An often requested feature is to be able to mount versioned routes on `/api`. This can easily be accomplished with `version_prefix`. :--:1 +```python +# /v1/my/path +app.route("/my/path", version=1, version_prefix="/api/v") +``` +:--- + +---:1 Perhaps a more compelling usage is to load all `/api` routes into a single `BlueprintGroup`. :--:1 +```python +# /v1/my/path +app = Sanic(__name__) +v2ip = Blueprint("v2ip", url_prefix="/ip", version=2) +api = Blueprint.group(v2ip, version_prefix="/api/version") + +# /api/version2/ip +@v2ip.get("/") +async def handler(request): + return text(request.ip) + +app.blueprint(api) +``` +:--- + +We can therefore learn that a route's URI is: + +``` +version_prefix + version + url_prefix + URI definition +``` + +::: tip Just like with `url_prefix`, it is possible to define path parameters inside a `version_prefix`. It is perfectly legitimate to do this. Just remember that every route will have that parameter injected into the handler. + +```python +version_prefix="/| + definition + | + ++ example + | + ++ filename + | + ++ extension + | +
|---|---|---|---|
|
+ \ |
+
+ + page.txt + | + +
+ "page"
+ |
+
+
+ "txt"
+ |
+
|
+ \ |
+
+ + cat.jpg + | + +
+ "cat"
+ |
+
+
+ "jpg"
+ |
+
+ \|
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | cat.jpg | |
+ "cat" | "jpg"
+ |
|
+ |
+
+ + 123.txt + | + +
+ 123
+ |
+
+
+ "txt"
+ |
+
+ |
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | 123.svg | |
+ 123 | "svg"
+ |
|
+ |
+
+ + 3.14.tar.gz + | + +
+ 3.14
+ |
+
+
+ "tar.gz"
+ |
+
| + definition + | + ++ example + | + ++ filename + | + ++ extension + | +
|---|---|---|---|
|
+ \ |
+
+ + page.txt + | + +
+ "page"
+ |
+
+
+ "txt"
+ |
+
|
+ \ |
+
+ + cat.jpg + | + +
+ "cat"
+ |
+
+
+ "jpg"
+ |
+
+ \|
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | cat.jpg | |
+ "cat" | "jpg"
+ |
|
+ |
+
+ + 123.txt + | + +
+ 123
+ |
+
+
+ "txt"
+ |
+
+ |
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | 123.svg | |
+ 123 | "svg"
+ |
|
+ |
+
+ + 3.14.tar.gz + | + +
+ 3.14
+ |
+
+
+ "tar.gz"
+ |
+
Hello world!
") +``` +:--- + +## Per Blueprint Group + +---:1 In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint group. The same will be inherited to all the blueprint grouped under it if the blueprints don't already override the same information with a value specified while creating a blueprint instance. + +When using blueprint groups for managing the versions, the following order is followed to apply the Version prefix to the routes being registered. + +1. Route Level configuration +2. Blueprint level configuration +3. Blueprint Group level configuration + +If we find a more pointed versioning specification, we will pick that over the more generic versioning specification provided under the Blueprint or Blueprint Group :--:1 +```python +from sanic.blueprints import Blueprint +from sanic.response import json + +bp1 = Blueprint( + name="blueprint-1", + url_prefix="/bp1", + version=1.25, +) +bp2 = Blueprint( + name="blueprint-2", + url_prefix="/bp2", +) + +group = Blueprint.group( + [bp1, bp2], + url_prefix="/bp-group", + version="v2", +) + +# GET /v1.25/bp-group/bp1/endpoint-1 +@bp1.get("/endpoint-1") +async def handle_endpoint_1_bp1(request): + return json({"Source": "blueprint-1/endpoint-1"}) + +# GET /v2/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-1") +async def handle_endpoint_1_bp2(request): + return json({"Source": "blueprint-2/endpoint-1"}) + +# GET /v1/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-2", version=1) +async def handle_endpoint_2_bp2(request): + return json({"Source": "blueprint-2/endpoint-2"}) +``` +:--- + +## Version prefix + +As seen above, the `version` that is applied to a route is **always** the first segment in the generated URI path. Therefore, to make it possible to add path segments before the version, every place that a `version` argument is passed, you can also pass `version_prefix`. + +The `version_prefix` argument can be defined in: + +- `app.route` and `bp.route` decorators (and all the convenience decorators also) +- `Blueprint` instantiation +- `Blueprint.group` constructor +- `BlueprintGroup` instantiation +- `app.blueprint` registration + +If there are definitions in multiple places, a more specific definition overrides a more general. This list provides that hierarchy. + +The default value of `version_prefix` is `/v`. + +---:1 An often requested feature is to be able to mount versioned routes on `/api`. This can easily be accomplished with `version_prefix`. :--:1 +```python +# /v1/my/path +app.route("/my/path", version=1, version_prefix="/api/v") +``` +:--- + +---:1 Perhaps a more compelling usage is to load all `/api` routes into a single `BlueprintGroup`. :--:1 +```python +# /v1/my/path +app = Sanic(__name__) +v2ip = Blueprint("v2ip", url_prefix="/ip", version=2) +api = Blueprint.group(v2ip, version_prefix="/api/version") + +# /api/version2/ip +@v2ip.get("/") +async def handler(request): + return text(request.ip) + +app.blueprint(api) +``` +:--- + +We can therefore learn that a route's URI is: + +``` +version_prefix + version + url_prefix + URI definition +``` + +::: tip Just like with `url_prefix`, it is possible to define path parameters inside a `version_prefix`. It is perfectly legitimate to do this. Just remember that every route will have that parameter injected into the handler. + +```python +version_prefix="/| + definition + | + ++ example + | + ++ filename + | + ++ extension + | +
|---|---|---|---|
|
+ \ |
+
+ + page.txt + | + +
+ "page"
+ |
+
+
+ "txt"
+ |
+
|
+ \ |
+
+ + cat.jpg + | + +
+ "cat"
+ |
+
+
+ "jpg"
+ |
+
+ \|
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | cat.jpg | |
+ "cat" | "jpg"
+ |
|
+ |
+
+ + 123.txt + | + +
+ 123
+ |
+
+
+ "txt"
+ |
+
+ |
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | 123.svg | |
+ 123 | "svg"
+ |
|
+ |
+
+ + 3.14.tar.gz + | + +
+ 3.14
+ |
+
+
+ "tar.gz"
+ |
+
| + definition + | + ++ example + | + ++ filename + | + ++ extension + | +
|---|---|---|---|
|
+ \ |
+
+ + page.txt + | + +
+ "page"
+ |
+
+
+ "txt"
+ |
+
|
+ \ |
+
+ + cat.jpg + | + +
+ "cat"
+ |
+
+
+ "jpg"
+ |
+
+ \|
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | cat.jpg | |
+ "cat" | "jpg"
+ |
|
+ |
+
+ + 123.txt + | + +
+ 123
+ |
+
+
+ "txt"
+ |
+
+ |
+ png\
+ |
+
+
+ gif\
+ |
+
+
+ svg> | 123.svg | |
+ 123 | "svg"
+ |
|
+ |
+
+ + 3.14.tar.gz + | + +
+ 3.14
+ |
+
+
+ "tar.gz"
+ |
+
Hello world!
") +``` +:--- + +## Per Blueprint Group + +---:1 In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint group. The same will be inherited to all the blueprint grouped under it if the blueprints don't already override the same information with a value specified while creating a blueprint instance. + +When using blueprint groups for managing the versions, the following order is followed to apply the Version prefix to the routes being registered. + +1. Route Level configuration +2. Blueprint level configuration +3. Blueprint Group level configuration + +If we find a more pointed versioning specification, we will pick that over the more generic versioning specification provided under the Blueprint or Blueprint Group :--:1 +```python +from sanic.blueprints import Blueprint +from sanic.response import json + +bp1 = Blueprint( + name="blueprint-1", + url_prefix="/bp1", + version=1.25, +) +bp2 = Blueprint( + name="blueprint-2", + url_prefix="/bp2", +) + +group = Blueprint.group( + [bp1, bp2], + url_prefix="/bp-group", + version="v2", +) + +# GET /v1.25/bp-group/bp1/endpoint-1 +@bp1.get("/endpoint-1") +async def handle_endpoint_1_bp1(request): + return json({"Source": "blueprint-1/endpoint-1"}) + +# GET /v2/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-1") +async def handle_endpoint_1_bp2(request): + return json({"Source": "blueprint-2/endpoint-1"}) + +# GET /v1/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-2", version=1) +async def handle_endpoint_2_bp2(request): + return json({"Source": "blueprint-2/endpoint-2"}) +``` +:--- + +## Version prefix + +As seen above, the `version` that is applied to a route is **always** the first segment in the generated URI path. Therefore, to make it possible to add path segments before the version, every place that a `version` argument is passed, you can also pass `version_prefix`. + +The `version_prefix` argument can be defined in: + +- `app.route` and `bp.route` decorators (and all the convenience decorators also) +- `Blueprint` instantiation +- `Blueprint.group` constructor +- `BlueprintGroup` instantiation +- `app.blueprint` registration + +If there are definitions in multiple places, a more specific definition overrides a more general. This list provides that hierarchy. + +The default value of `version_prefix` is `/v`. + +---:1 An often requested feature is to be able to mount versioned routes on `/api`. This can easily be accomplished with `version_prefix`. :--:1 +```python +# /v1/my/path +app.route("/my/path", version=1, version_prefix="/api/v") +``` +:--- + +---:1 Perhaps a more compelling usage is to load all `/api` routes into a single `BlueprintGroup`. :--:1 +```python +# /v1/my/path +app = Sanic(__name__) +v2ip = Blueprint("v2ip", url_prefix="/ip", version=2) +api = Blueprint.group(v2ip, version_prefix="/api/version") + +# /api/version2/ip +@v2ip.get("/") +async def handler(request): + return text(request.ip) + +app.blueprint(api) +``` +:--- + +We can therefore learn that a route's URI is: + +``` +version_prefix + version + url_prefix + URI definition +``` + +::: tip Just like with `url_prefix`, it is possible to define path parameters inside a `version_prefix`. It is perfectly legitimate to do this. Just remember that every route will have that parameter injected into the handler. + +```python +version_prefix="/