URI Templates support

URI templates are a way to specify variable parts of your resources. Implementation and syntax is based on RFC 6570. In the simplest case, you just insert a variable in path:

GET /payment/{id}

This would match requests like

curl "http://your.vanity.apiary.io/payment/123"
Please note that variable names can contain underscores, but not dashes. (/payment/{payment_id} is valid, but /payment/{payment-id} is not) When multiple blueprint resource definition match same request, an exact match is preferred to a template expansion. That way, you can create a generic URL template response and single out special edge cases:

GET /payment/{id}
< 200
{
  "type" : "templated"
}

GET /payment/123
< 200
{
  "type" : "special case, matched without a template"
}

QueryString parameters

Apiary also supports URLs with query string arguments (following a question-mark character, ampersand separated). Order of the arguments in request is not significant.

GET /payments{?year,month}

would match the following request:

curl "http://your.vanity.apiary.io/payments?year=2012&month=08"

Templates, of course, may be combined

GET /payments/customers/{customer_id}/{?year,month}

Crosshair expansion is also supported, so

GET /payments/{#position}

would match

curl "http://your.vanity.apiary.io/payments#123"

For query string arguments, explode modifier is supported

GET /payments{?year*}

would match

curl "http://your.vanity.apiary.io/payments?year=2011&year=2012&year=2013"

If a parameter is specified in blueprint, it is required. You may differentiate a request based on non-templated parameters, but template parameters must then use ampersand-based expansion instead of question mark one. This is valid:

GET /resource?type=a{&year,month}

GET /resource?type=b{&year,month}

If a request contains query parameter not specified in blueprint, it is ignored. Thus, resource above would be matched by

curl "http://your.vanity.apiary.io/resource?type=b&year=2011&month=12&leftover=true"

Limitations

Following features from RFC is not supported (yet). You most likely don't need them - at least we feel they're not relevant to API Documentation. If you feel otherwise, please let us know.

If same resource with both with and without explode modifier is specified and called with multiple parameters, version with explode modifier is not preferred. 

If request is made with exactly same request path as the raw template text is, that template is matched regardless of what template semantically describes.

Querystring parameters must be specified as in RFC (examples above). This resource would not be matched:

GET /resource?year={year}&month={month}

If there are two matching resources and one contains "reserved expansion", then the one with reserved expansion will be preferred
GET /{path_fragment}/whatever

GET /{+path}

If there are two matching resources containing "reserved expansion", then the shortest one will be preferred:
GET /{+path_fragment}/whatever

GET /{+path}

Feedback and Knowledge Base