URI Templates

This also provides instructions for Apiary to provide mock servers, debugging servers, console, and more.

Apiary tries to conform to RFC 6570 when parsing these templates. This document will aim to cover how to use this feature within Apiary.

Basic Usage

URI Templates are handy for expressing variables within a URL, such as a path variable or a query variable. This is done through using curly brackets as shown below.

/users/{id}/{?query1,query2}

In this example, there are three variables.

• id - A path variable that is required for a valid URL
• query1 (optional) - A query variable
• query2 (optional) - Another query variable

To express this in API Blueprint, it would look like this.

FORMAT: 1A

# Example API

## User [/user/{id}{?query1,query2}]

+ Parameters
    + id - A path variable that is required for a valid URL
    + query1 (optional) - A query variable
    + query2 (optional) - Another query variable

### Retreive [GET]
+ Response 204

Variable Expansion

Path variables allow for defining variables within a URL that are part of the URL path. Path variables are required because the path must be valid in order to be a valid URL.

Path variables are useful for defining IDs or UUIDs that are part of the URL, which is a common pattern seen in many HTTP APIs.

Query Variables Expansion

A query variable may be defined with curly brackets like any other variable, but they have a special syntax. They are expressed by adding a question mark after the first curly bracket followed by the query variables separated by commas without spaces (which is important).

/user/{id}/{?query1,query2}

This shows two query variables that are optional for creating a resolvable URL.

Describing Variables in API Blueprint

Within API Blueprint, as shown in the example above, you can define the variables in simple Markdown syntax. For more examples on defining URL template variables, see the example in the API Blueprint repository.

Unsupported

There are several parts of the URI Template specification RFC 6570 that is not supported. These include:

• Label Expansion
• Path Segment Expansion
• Path Style Parameter Expansion

Testing URL Templates

For testing templates, you can use the tool found at https://bigbluehat.github.io/vue-uri/.

Encoding Unreserved Characters

variables as written within the curly brackets MUST have unreserved characters percent-encoded. This means characters like periods or greater-than or less-than signs MUST be percent-encoded in order for the URL template to work correctly.

For example, if you are wanting to define a query variable user.name, you would do so as following, where the period is replaced with %2e.

http://example.com/{?user%2ename}