145 lines
4.6 KiB
ReStructuredText
145 lines
4.6 KiB
ReStructuredText
URI Templates (Advanced)
|
|
========================
|
|
|
|
In `URI Templates`_, we looked at the most common ways to use URI Templates. Here, we'll look at some of the extended syntaxes that URI Templates provide.
|
|
|
|
Path Components
|
|
^^^^^^^^^^^^^^^
|
|
|
|
To match a path component, include a slash ``/`` at the beginning of the variable expression. This instructs the template to match the variable if it:
|
|
|
|
- Begins with ``/``
|
|
- Contains only unreserved and percent-encoded characters
|
|
|
|
You may also use the explode (``*``) modifier to match a variable number of path components and provide them as an array. When using the explode (``*``) modifier to match paths components, the ``/`` character serves as the delimiter instead of a comma.
|
|
|
|
.. list-table:: Matching path components
|
|
:header-rows: 1
|
|
|
|
* - Template
|
|
- Path
|
|
- Match?
|
|
- Attributes
|
|
* - {/path}
|
|
- /hello.html
|
|
- Yes
|
|
- :path: ``"hello.html"``
|
|
* - {/path}
|
|
- /too/many/parts.jpg
|
|
- No
|
|
-
|
|
* - {/one}{/two}{/three}
|
|
- /just/enough/parts.jpg
|
|
- Yes
|
|
- :one: ``"just"``
|
|
:two: ``"enough"``
|
|
:three: ``"parts.jpg"``
|
|
* - {/path*}
|
|
- /any/number/of/parts.jpg
|
|
- Yes
|
|
- :path: ``["any", "number", "of", "parts.jpg"]``
|
|
* - /image{/image*}.jpg
|
|
- /image/with/any/path.jpg
|
|
- Yes
|
|
- :image: ``["with", "any", "path"]``
|
|
|
|
.. note::
|
|
|
|
The template ``{/path}`` fails to match the path ``/too/many/parts.jpg``. Although the path does begin with a slash, the subsequent slashes are reserved characters, and therefore the match fails. To match a variable number of path components, use the explode ``*`` modifier (e.g, ``{/paths*}``), or use the reserved (``+``) operator (e.g., ``/{+paths}``).
|
|
|
|
Dot Prefixes
|
|
^^^^^^^^^^^^
|
|
|
|
Dot prefixes work similarly to matching path components, but a dot ``.`` is the prefix character in place of a slash. This may be useful for file extensions, etc.
|
|
|
|
Including a dot ``.`` at the beginning of the variable expression instructs the template to match the variable if it:
|
|
|
|
- Begins with ``.``
|
|
- Contains only unreserved (including ``.``) and percent-encoded characters
|
|
|
|
You may also use the explode (``*``) modifier to match a variable number of dot-prefixed segments and store them to an array. When using the explode (``*``) modifier to match paths components, the ``.`` character serves as the delimiter instead of a comma.
|
|
|
|
.. list-table:: Matching dot prefixes
|
|
:header-rows: 1
|
|
|
|
* - Template
|
|
- Path
|
|
- Match?
|
|
- Attributes
|
|
* - /file{.ext}
|
|
- /file.jpg
|
|
- Yes
|
|
- :ext: ``"jpg"``
|
|
* - /file{.ext}
|
|
- /file.tar.gz
|
|
- Yes
|
|
- :ext: ``"tar.gz"``
|
|
* - /file{.ext1}{.ext2}
|
|
- /file.tar.gz
|
|
- Yes
|
|
- :ext1: ``"tar"``
|
|
:ext2: ``"gz"``
|
|
* - /file{.ext*}
|
|
- /file.tar.gz
|
|
- Yes
|
|
- :ext: ``["tar", "gz"]``
|
|
|
|
.. note::
|
|
|
|
Because ``.`` is an unreserved character, the template ``/file{.ext}`` matches the path ``/file.tar.gz`` and provides the value ``"tar.gz"``. This is different from the behavior of the slash prefix, where an unexpected slash causes the match to fail.
|
|
|
|
Multiple-variable Expressions
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
An expression in a URI template may contain more than one variable. For example, the template ``/aliases/{one},{two},{three}`` can be written as ``/aliases/{one,two,three}``.
|
|
|
|
The delimiter between the matched variables is the same as when matching with the explode (``*``) modifier:
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - Type
|
|
- Delimiter
|
|
* - Simple String
|
|
- Comma ``,``
|
|
* - Reserved
|
|
- Comma ``,``
|
|
* - Path Components
|
|
- Slash ``/``
|
|
* - Dot Prefix
|
|
- Dot ``.``
|
|
|
|
.. list-table:: Multiple-variable expressions
|
|
:header-rows: 1
|
|
|
|
* - Template
|
|
- Path
|
|
- Attributes
|
|
* - /{one,two,three}
|
|
- /fry,leela,bender
|
|
- :one: ``"fry"``
|
|
:two: ``"leela"``
|
|
:three: ``"bender"``
|
|
* - /{one,two,three}
|
|
- /fry,leela,Nixon%27s%20head
|
|
- :one: ``"fry"``
|
|
:two: ``"leela"``
|
|
:three: ``"Nixon's head"``
|
|
* - /{+one,two,three}
|
|
- /fry,leela,Nixon's+head
|
|
- :one: ``"fry"``
|
|
:two: ``"leela"``
|
|
:three: ``"Nixon's head"``
|
|
* - /{/one,two,three}
|
|
- /fry/leela/bender
|
|
- :one: ``"fry"``
|
|
:two: ``"leela"``
|
|
:three: ``"bender"``
|
|
* - /file{.one,two,three}
|
|
- /file.fry.leela.bender
|
|
- :one: ``"fry"``
|
|
:two: ``"leela"``
|
|
:three: ``"bender"``
|
|
|
|
.. _URI Templates: uri-templates.html
|