T
rfc6570 uri-template api-design rest web-standards

URI Template Explained: Master RFC 6570 for API Design

Learn how to define and expand URI templates using RFC 6570. A must-know standard for building robust and flexible RESTful APIs.

2026-04-11

URI Template Explained: Master RFC 6570

When building RESTful APIs, one of the most important concepts is how to represent resources using URIs. Hardcoding URLs is brittle and leads to maintenance nightmares. RFC 6570 (URI Template) provides a standardized way to describe a URI with placeholders that can be expanded into a final URI.

In this guide, we'll dive deep into how URI templates work, the different expression types, and why they are essential for modern web development.

What is a URI Template?

A URI Template is a string that contains variables wrapped in curly braces {}. These variables are replaced with actual values during a process called expansion.

Basic Example:

Template: http://api.example.com/users/{id} Variables: { "id": "123" } Expansion: http://api.example.com/users/123

The 8 Levels of URI Templates

RFC 6570 defines several levels of complexity for expansion. Here are the most common ones:

1. Simple String Expansion {var}

Used for simple path segments.

  • Template: /{var}
  • Values: {"var": "value"}
  • Result: /value

2. Reserved Character Expansion {+var}

Similar to simple expansion, but it allows reserved characters (like /, ?, #) without percent-encoding them.

  • Template: /{+path}/index.html
  • Values: {"path": "foo/bar"}
  • Result: /foo/bar/index.html

3. Fragment Expansion {#var}

Used for URI fragments.

  • Template: {#var}
  • Values: {"var": "section1"}
  • Result: #section1

4. Label Expansion with Dot {.var}

Commonly used for file extensions.

  • Template: /config{.format}
  • Values: {"format": "json"}
  • Result: /config.json

5. Path Segment Expansion {/var}

Automatically adds a leading slash.

  • Template: {/var}
  • Values: {"var": "user"}
  • Result: /user

6. Query Parameter Expansion {?var}

The most common type for API search and filtering.

  • Template: /search{?q,lang}
  • Values: {"q": "test", "lang": "en"}
  • Result: /search?q=test&lang=en

Variable Modifiers

URI Templates also support modifiers to control how variables are expanded.

  • Explode (*): Used for arrays or objects.
    • Template: /users{?id*}
    • Values: {"id": [1, 2, 3]}
    • Result: /users?id=1&id=2&id=3
  • Prefix (:n): Only takes the first n characters.
    • Template: /{var:3}
    • Values: {"var": "abcdef"}
    • Result: /abc

Why Use URI Templates?

  1. Decoupling: The client doesn't need to know how to construct the URL; it just needs the template and the variables.
  2. HATEOAS: Essential for Hypermedia as the Engine of Application State. Servers can provide templates in their responses.
  3. Consistency: Provides a standard way to handle query parameters and path segments across different programming languages and libraries.

FAQ

Q: Is {var} the same as :var used in many routers? A: Conceptually, yes, but RFC 6570 is the official standard for how these should be represented in documentation and hypermedia. Most routers (like Express or React Router) use a simplified proprietary syntax.

Q: How do I handle reserved characters? A: By default, simple expansion {var} will percent-encode reserved characters. Use {+var} if you want to keep them as-is.

Q: Are URI templates case-sensitive? A: Variable names are case-sensitive according to the spec. {var} and {VAR} are different variables.

Related Tools

  • URL Encoder/Decoder - Use this to check how characters are encoded during template expansion.
  • JSON Formatter - Format the JSON data you use to fill your templates.
  • Regex Tester - Test the patterns you use to validate URI segments.
Back to Blog