URITemplate.md

URI templates

URI template syntax

But we have RFC6570, why another one?

Current implementation have more questions than answers:

1. It describes only template expansion, not matching. While URI matching is more common task (routing) - any template standard which doesn't describe matching will fail
2. The RFC6570 modifiers sometimes is pointless and create more pain than gain for developers
3. Some array and object expansions doesn't meet the real life needs

General requirements

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Expression

• 0. Expression
• 0.1. Template expression MUST be surrounded by the curly braces: { and }
• 0.2. Expression MUST contain at least one variable name
• 0.2.1. Variable name SHOULD start with uppercase letter, lowercase letter, low line (U+005F) _ or dollar sign (U+0024) $
• 0.2.3. The rest of variable name MAY contain the same characters, plus digits and hyphen-minus (U+002D)
• 0.2.4. Variable name MUST NOT contain space or comma
• 0.3. Expression MAY be prefixed with one of reserved operators described below
• 0.3.1. Operator and variable name MAY or MAY NOT be divided by space

Requirements

Level 1 - simple variable

1.1. Expansion

• 1.1.1. When variable value is a string – it SHOULD be properly encoded as described in section 2 of [RFC3986](http://www.ietf- .org/rfc/rfc3986.txt)
• 1.1.2. When variable value is a number - it MUST be converted to the string as is, without conversion to the different numeral - system or rounding.
• 1.1.3. When variable value is nullable, i.e. false, null or undefined - it should be interpreted as empty string
• 1.1.4. When variable value is array (list) of values - members SHOULD be concatenated with comma (U+002C) ,
• 1.1.4.1. Each member SHOULD be handled as single variable value as described in section 1.1.1., 1.1.2 and 1.1.3.
• 1.1.5. When variable value is an object (hash map) - each key and value SHOULD be divided by equals sign (U+003D) = and - concatenated with comma (U+002C) ,
• 1.1.5.1. Each key and value SHOULD be handled as single variable value as described in section 1.1.1., 1.1.2 and 1.1.3.

Example

Given:

section := "users"
number := -2.5
list := ["one", 2, "three"]
object := { one: 1, special: '%', string: 'föô' }

Expansions:

"/~{section}" => "/~users"
"/{number}" => "-2.5"
"/{list}" => "/one,2,tree"
"/{object}" => "/one=1,special=%25,string=f%C3%B6%C3%B4"
"/{section}/plain/{number}" => "/users/plain/-2.5"

1.2. Matching

1.2.