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.
Matching path components
Template |
Path |
Match? |
Attributes |
{/path} |
/hello.html |
Yes |
|
{/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.
Matching dot prefixes
Template |
Path |
Match? |
Attributes |
/file{.ext} |
/file.jpg |
Yes |
|
/file{.ext} |
/file.tar.gz |
Yes |
|
/file{.ext1}{.ext2} |
/file.tar.gz |
Yes |
|
/file{.ext*} |
/file.tar.gz |
Yes |
|
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:
Type |
Delimiter |
Simple String |
Comma , |
Reserved |
Comma , |
Path Components |
Slash / |
Dot Prefix |
Dot . |
Multiple-variable expressions
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" |
|