URI Template Format

Url templates are compiled with geraintluff/uri-templates, which fully implements RFC 6570 level 4.

Overview

Url templates use variable expansion using single curly braces (ie {variable}). Certain prefixes alter the way variables are expanded.

Prefixes

• + - Reserved Expansion
• / - Path Segments
• ? - Query Expansion
• & - Query Continuation
• # - Fragment Expansion
• . - Label Expansion
• ; - Path-style Parameters

Mofidiers

• : - The Prefix Modifier limits the number of characters expanded, like truncate.
• * - The Explode Modifier indicates that each member in a collection is to be expanded as a separate value.

Examples

The following examples use the following inputs to demonstrate how different inputs are expanded.

{
  "undef": undefined,
  "id": 123,
  "key": "abcdef",
  "string": "Hello World!",
  "path": "/foo/bar",
  "host": "http://example.com",
  "list": ["red", "green", "blue"],
  "list[]": ["magenta", "cyan", "yellow"],
  "object": { "category": "featured", "enabled": true },
}

String Expansion

Expression	Expansion
{string}	Hello%20World%21
{string:6}	Hello%20
/photos/{id}	/photos/123
{path}	%2Ffoo%2Fbar
{host}	http%3A%2F%2Fexample.com
{list}	red,green,blue
{object}	category,featured,enabled,true
{object*}	category=featured,enabled=true

Reserved Expansion

Expression	Expansion
{+string}	Hello World!
{+path}	/foo/bar
{+host}	http://example.com

Path Segments

Expression	Expansion
{/string}	/Hello%20World%21
{/undef}	(empty string)
{/list}	/red,green,blue
{/list*}	/red/green/blue
{/key,id}	/abcdef/123

Query Expansion

Expression	Expansion
{?undef}	(empty string)
{?key,id}	?key=abcdef&id=123
{?list}	?red,green,blue
{?list*}	?v=red&v=green&v=blue
{?list[]*}	?list[]=magenta&list[]=cyan&list[]=yellow
{?object}	?category,featured,enabled,true
{?object*}	?category=featured&enabled=true
{?object*,key}	?category=featured&enabled=true&key=abcdef

Query Continuation

Expression	Expansion
{&undef}	(empty string)
{&key,id}	&key=abcdef&id=123
{?key}{&id}	?key=abcdef&id=123
{&list*}	&v=red&v=green&v=blue
{&list[]*}	&list[]=magenta&list[]=cyan&list[]=yellow
{&object*}	&category=featured&enabled=true
{&object*,key}	&category=featured&enabled=true&key=abcdef

Other Options

URI Templates are extremely powerful and not fully documented here.

To learn about all of the possibilities, check out the RFC.