URL templates and REST operations

URL Templates and REST Operations

Overview

WebServius uses URL templates to distinguish between different operations in the same REST service. Each operation can cost a different number of units per call. Also, individual operations may be blocked using the Access Policy feature of WebServius.

A template describes a set of URLs relative to the base URL of your service. For example, consider the following template table:

URL Template	Units per Call
*	1
alaska	2
{state}/{city}	10

Suppose also that the URL of this service is http://svc.webservius.com/v1/acme/weather

The table means that a request to http://svc.webservius.com/v1/acme/weather/Idaho will be counted as 1 unit, a request to http://svc.webservius.com/v1/acme/weather/Alaska will be counted as 2 units, and a request to a request to http://svc.webservius.com/v1/acme/weather/California/SanDiego will be counted as 10 units.

This gives you significant flexibility in designing usage, pricing and access plans for your services. To use this feature, you must learn how to create valid URL templates, and then how to combine them into tables of REST operations. This is covered below.

Creating a URL template

A template has two parts: a path and an optional query. For example, weatherForecast/{state}/{city}?date={date} (here, weatherForecast/{state}/{city} is the path and ?date={date} is the query).

The template should never start with a slash. A trailing slash is optional in the path. A path consists of a series of segments separated by '/'. Each segment can have a literal value, a variable name (written in {curly braces}), or a wildcard (written as '*'). In the previous template the "weatherForecast” segment is a literal value while "{state}" and "{city}" are variables. The wildcard is optional, but can only appear at the end of the URI, where it matches “the rest of the path” (which may contain multiple segments).

A path segment may contain a mix of variables and literals. For example, you may define a template such as weather/ForecastFor{zipcode}.xml – in this case, the second segment consists of a literal “ForecastFor”, the variable “{zipcode}”, and the literal “.xml”.

The query expression, if present, specifies a series of name/value pairs separated by '&'. The order of these pairs does not matter. Elements of the query string can either be literal pairs (e.g. “forecast=detailed”) or a variable pair (e.g. “date={date}”). Only the right side of the equal sign can have a variable. Query expressions without the equal sign (e.g. “?x”) are not permitted. If no query is specified, the URL template will match any query.

All template variable names (the text inside the curly braces) within a template string must be unique, and are case-insensitive. Variables names are only needed for readability and are otherwise ignored by WebServius.

Path segments are case-insensitive (the template weather on base URL http://example.com will match http://example.com/WeAtHeR), except for some international characters (like accented vowels) which are treated in a case-sensitive way. Query strings, however, are case-sensitive.

URL templates should be specified in URL-encoded form if special characters like spaces are present (e.g. “weather%20tomorrow” to represent “weather tomorrow”). The template “*” matches any URL, and is the default operation you get for any new service. If you add operations in addition to it, they will be used if there is a match, and “*” will be used as a fallback if there is no match. If “*” is removed, only requests that match the other operations you’ve added will be allowed through. See “How REST operations are selected based on the request” below for more information.

Creating an unambiguous table of REST operations

The operations you define cannot contain URI templates that are the same. Templates are “the same” when they have the same number of segments, all the literals are the same, and the variables are in the same places. If you try to add two operations that are the same, an error will occur and your service will fail to activate.

For example, you cannot have these two operations at the same time: weather/{city}?date={date}&style=detailed and WEATHER/{state}?style=detailed&date={date}. These operations only differ in variable names (“city” vs. “state”) which are ignored, case of “weather” which is ignored, and order of query parameters which is also ignored. So, if a request comes in for http://example.com/wEaThEr/washington?date=01-01-2009&style=detailed, WebServius would be unable to figure out which of these two operations is being invoked.

You can have more than one template with the same path, as long as the query strings are not ambiguous. For example, you can have one operation with the template weather/{city}?style=short and another with the template weather/{city}?style=detailed.

Query parameters that are not present in the template query string are ignored when matching. For example, if the first operation is weather/{city} and the second is weather/{city}?style=detailed, then http://example.com/weather/Mami?style=unknown will match the first operation (“style=unknown” is ignored), and http://example.com/weather/Miami?date=01-01-2009&style=detailed will match the second operation (“date=01-01-2009” is ignored).

Specifying different query parameters in two operations may lead to ambiguity, which is forbidden. For example, if one operation is weather/{city}?season=winter and the other is weather/{city}?time=day, then http://example.com/weather/Miami?time=day&season=winter is ambiguous (could match either operation). Therefore, you may not specify two such operations for the same service. Doing so may cause your service to fail on activation. One way to remove the ambiguity is to introduce a third parameter to differentiate between the two operations. For example, having one operation with the template weather/{city}?type=longTerm&season=winter and another with the template weather/{city}?type=shortTerm&time=day is allowed, because “type” removes the ambiguity.

You cannot specify, for the same query string variable, a variable in one operation and a literal in another operation. For example, you cannot have one operation with the template weather?state=Alaska and another with the template weather?state={state}. If you want to special-case a particular query variable value (e.g. separate out Alaska as in this example), make the second operation simply weather (i.e. omit the special-cased variable altogether).

However, if there are no literals, you can have two operations where one has a variable and another omits the parameter completely. For example, if one operation is weather and the other is weather?state={state}, the first operation will match when the “state” parameter is not present, and the second will match when it is present (regardless of its value).

Combining URL templates with WebServius URLs

The URL templates you create should only contain items specific to your service. Do not specify any standard URL components that are automatically managed by WebServius.

Consider a subscriber request URL sent to WebServius, such as http://svc.webservius.com/v1/acme/weather/getForecast?wsvKey=abc123&city=Miami. It has the base WebServius address with the provider name and service name (http://wvc.webservius.com/v1/acme/weather), a relative path (getForecast), and a query string consisting of the WebServus key (wsvKey=abc123) and service-specific parameters (city=Miami), in any order.

When specifying URL templates, only the relative path and service-specific query parameters matter. For example, “*”, “getForecast” and “getForecast?city=Miami” would be valid URL templates, but templates such as “v1/acme/weather/getForecast” and “getForecast?wsvKey={key}” will not work.

The subscriber request URL is mapped to a base service URL that you provided during enrolment. For example, if you provided the address “http://example.com/myPath?myKey=12345”, the request above will be forwarded to “http://example.com/myPath/getForecast?myKey=12345&city=Miami”. Do not specify any part of the base URL (such as “myPath” or “myKey”) in the URL templates you create. So, a valid URL template would be “getForecast” and “getForecast?city=Miami”, but never “myPath/getForecast” or “getForecast?city=Miami&myKey={myKey}”.

How REST operations are selected based on the request

The most specific matching operation is always selected. The most specific matching operation is one where the most segments match (ignoring the query string, assuming it matches). For example, if there are operations a?x=1&y=2&z=3, a/b, and a/b/c, then a request to http://example.com/a/b/c?x=1&y=2&z=3 will match the a/b/c operation. The “*” segment is not counted when determining the operation with the most matches, and so the “*” operation always matches last (i.e. only if nothing else matches).

Source

This document is adapted from http://msdn.microsoft.com/en-us/library/bb675245.aspx but contains important WebServius-specific differences.