Access Control and Usage Metering based on URLs

Overview

When you subscribe to a service, you need to be aware of “units” of usage. The service provider may allow a certain number of free “units” (e.g. 1,000 units per day). If you sign up for a paid service, you may be required to pay based on the “units” you use (e.g. 1 cent for every unit).

In many cases, every time you call the service, you use up exactly 1 unit of usage. But this is not always the case.

To figure out how many units a given call to the service will cost you, take a look at the URL table in the “Access and Metering Policy” section (you may have to click on the “+” sign to expand it). You will see a table like this:

The table means that:

Each row in the table is called an “operation”. For each request, you only use up units for one operation, and the most specific operation is used (for example, http://svc.webservius.com/v1/acme/weather/Alaska is counted as 2 units, even though it also matches the first operation with the “*”).

Normally, the rules for matching your request to operations are self-explanatory. However, in some cases you may require more advanced knowledge of this process. This is explained below.

Advanced Information on URL matching: URL Templates

Operations are defined by their “URL templates”. This is the part of the URL shown after “http://svc.webservius.com/v1/{providerName}/{serviceName}/”. For example, the first two URL templates shown in the table above are * and alaska.

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).

A path consists of a series of segments separated by '/' (a trailing slash may be present after the last segment, but means nothing). 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 can only appear at the end of the URI, and 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 see 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}”). Query parameters that are not present in the template are ignored when matching, and so a template like {state}?forecast=detailed matches the URL http://svc.webservius.com/v1/acme/weather/Idaho?time=night&forecast=detailed (the time=night parameter is ignored). As a result, if no query is specified, the URL template will match any query, and so a simpler template like {state} or even * also matches the above-mentioned URL. A template with a variable in the query string, like {state}?forecast={forecastType}, will match any value of the query parameter (“forecast” in this case), but will not match if the parameter is not present at all. WebServius-specific query parameters like wsvKey (used for sending the subscription secret key) are always ignored when matching URL templates.

Variables names (the text inside the curly braces) are only needed for readability and are otherwise ignored by WebServius.

Path segments are case-insensitive (the template alaska will match http://svc.webservius.com/v1/acme/weather/AlAsKa), except for some international characters (like accented vowels) which are treated in a case-sensitive way. Query strings, however, are case-sensitive. URL templates are usually specified in URL-encoded form if special characters like spaces are present (e.g. “weather%20tomorrow” to represent “weather tomorrow”).

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 with templates a?x=1&y=2&z=3, a/b, and a/b/c, then a request to http://svc.webservius.com/v1/acme/weather/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. (To say this another way: it only matches 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.