1. Overview
The purpose of this post is to propose a generic routing architecture that can be applied to web resource requests. The routing architecture is designed to provide a REST interface over a variety of web resources that are assumed to share the following properties:
· Resources may be localized to a specific culture.
· Resources are created on a specific date-time.
· Resources are assigned a unique identifier.
· Resources are assigned a human-readable title.
· Resources may be grouped in indexed collections.
Requests for resources with the above mention properties share a set of common criteria that can apply regardless of the resource being requested:
· Resources by culture.
· Resources by date
· Resources by date range.
· Resources by index range.
· Resource by title.
· Resource by unique identifier.
Many resource providers found on the web today, such as blogs, could benefit greatly from applying a common routing infrastructure that would enable end users to easily access resource or sets of resources in a consistent manner. To this end, listed below are 8 generic routes that can be applied to a wide variety of resources that together achieve the goal of providing an intuitive and consistent API that consumers may use when applying common selection criteria to published resources. This routing infrastructure targets the controller aspect of manipulating resources, while the actual presentation (view) is outside the scope of this discussion.
2. Routing Introduction
ASP.NET routing enables you to provide URLs that do not have to map to specific files in a web application. Because the URL does not have to map to a file, you can use URLs in a web application that are descriptive of the user's action and therefore more easily understood by users. In ASP.NET routing, you define URL patterns that contain placeholders for values that are used when you handle URL requests. At run time, the pieces of the URL that follow the application name are parsed into discrete values, based on a URL pattern that you have defined.
The URL patterns that you define are known as routes. In a route, you specify placeholders that are mapped to values that are parsed from the URL request. You can also specify constant values that are used for matching URL requests. In a route, you define placeholders (referred to as URL parameters) by enclosing them in braces, while the / character is interpreted as a delimiter when the URL is parsed. Information in the route definition that is not a delimiter and that is not in braces is treated as a constant value. Values that are extracted from between the delimiters are assigned to placeholders.
3. Localization
Resources will be localized using the routing segments {language}-{country} and/or {language} that should follow the resource controller segment of all routes. The default value of these routing parameters will be set to use the Accept-Language HTTP header sent with the resource request, and if not present will fall back to a configured neutral culture. Resource may be localized using an invariant culture, in which case they should be included in all requests for a given resource regardless of the localization criteria.
|
Route
|
Example
|
Description
|
|
/{controller}/{language}-{country}
|
/posts/es-MX
|
Returns all posts localized to use Spanish - Mexico.
|
|
/{controller}/{language}
|
/posts/es
|
Returns all posts localized to use Spanish.
|
|
/{ controller}
|
/posts
|
Returns all posts localized to use locale specified by the Accept-Language HTTP header. If unable to determine locale based on header, returns all posts localized to use the neutral culture.
|
4. Routing Constraints
In addition to matching a URL request to a route definition by the number of parameters in the URL, you can specify that values in the parameters meet certain constraints. If a URL contains values that are outside the constraints for a route, that route is not used to handle the request. You add constraints to make sure that the URL parameters contain values that will work in your application. Constraints are defined by using regular expressions or by using objects that implement the IRouteConstraint interface. The proposed routing architecture utilizes a small set of constraints that are used to validate the data type and validity of individual parameters in a route.
|
Name
|
Description
|
|
IsDateRouteConstraint
|
Determines if parameter matches the custom date-time format of yyyyMMdd.
|
|
IsDayRouteConstraint
|
Determines if parameter matches double digit representation of a day for a date-time.
|
|
IsGuidRouteConstraint
|
Determines if parameter is a GUID represented as a series of lower-case hexadecimal digits in groups of 8, 4, 4, 4, and 12 digits and separated by hyphens.
|
|
IsIntegerRouteConstraint
|
Determines if parameter is a 32-bit signed integer.
|
|
IsMonthRouteConstraint
|
Determines if parameter matches double digit representation of a month for a date-time.
|
|
IsNotEmptyStringRouteConstraint
|
Determines if parameter is not a null or empty string.
|
|
IsYearRouteConstraint
|
Determines if parameter matches four digit representation of a year for a date-time
|
5. Routes
The order routes are added to the routing table affects the how the routing engine evaluates the designated routes. In general, routes should be added in order from the most specific to the least specific, but keep in mind evaluation is also affected by any conditions that are applied to the route parameters. The routes defined below are in order of the most specific to the least specific.
|
Route
|
/{controller}/{language}-{country}/{year}/{month}/{day}
|
|
Name
|
ResourcesByYearMonthDay
|
|
Description
|
Manipulates the representation of the resources handled by the controller that are constrained by the specified year, month, and day.
|
|
Parameters
|
|
|
|
Name
|
Constraints
|
Description
|
|
|
controller
|
None
|
The component that handles the resource request.
|
|
|
language
|
IsNotEmptyStringRouteConstraint
|
A lowercase two-letter code derived from ISO 639-1 that specifies the language to localize resources in.
|
|
|
country
|
IsNotEmptyStringRouteConstraint
|
An uppercase two-letter code derived from ISO 3166 that specifies the country to localize resources in.
|
|
|
year
|
IsYearRouteConstraint
|
The year for the specified date-time, including the century. If the year is less than four digits in length, then preceding zeros are appended as necessary to make the displayed year four digits long.
|
|
|
month
|
IsMonthRouteConstraint
|
The month for the specified date-time, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is formatted with a preceding zero (01-09).
|
|
|
day
|
IsDayRouteConstraint
|
The day for the specified date-time, measured as a number between 1 and 31, inclusive. If the day is a single digit only (1-9), it is formatted with a preceding zero (01-09).
|
|
Examples
|
|
|
|
Example
|
Description
|
|
|
/posts/es-MX/2008/07/02
|
Returns all blog posts published on July 2nd, 2008 that are localized to use Spanish - Mexico.
|
|
|
/posts/es/2008/07/02
|
Returns all blog posts published on July 2nd, 2008 that are localized to use Spanish.
|
|
|
/posts/2008/07/02
|
Returns all blog posts that published on July 2nd, 2008 that are localized to use locale specified by the Accept-Language HTTP header or fallback neutral language.
|
| |
|
|
|
|
|
Route
|
/{controller}/{language}-{country}/{year}/{month}
|
|
Name
|
ResourcesByYearMonth
|
|
Description
|
Manipulates the representation of the resources handled by the controller that are constrained by the specified year, and month.
|
|
Parameters
|
|
|
|
Name
|
Constraints
|
Description
|
|
|
controller
|
None
|
The component that handles the resource request.
|
|
|
language
|
IsNotEmptyStringRouteConstraint
|
A lowercase two-letter code derived from ISO 639-1 that specifies the language to localize resources in.
|
|
|
country
|
IsNotEmptyStringRouteConstraint
|
An uppercase two-letter code derived from ISO 3166 that specifies the country to localize resources in.
|
|
|
year
|
IsYearRouteConstraint
|
The year for the specified date-time, including the century. If the year is less than four digits in length, then preceding zeros are appended as necessary to make the displayed year four digits long.
|
|
|
month
|
IsMonthRouteConstraint
|
The month for the specified date-time, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is formatted with a preceding zero (01-09).
|
|
Examples
|
|
|
|
Example
|
Description
|
|
|
/posts/es-MX/2008/07
|
Returns all blog posts published on July, 2008 that are localized to use Spanish - Mexico.
|
|
|
/posts/es/2008/07
|
Returns all blog posts published on July, 2008 that are localized to use Spanish.
|
|
|
/posts/2008/07
|
Returns all blog posts that published on July, 2008 that are localized to use locale specified by the Accept-Language HTTP header or fallback neutral language.
|
| |
|
|
|
|
|
Route
|
/{controller}/{language}-{country}/{year}
|
|
Name
|
ResourcesByYear
|
|
Description
|
Manipulates the representation of the resources handled by the controller that are constrained by the specified year.
|
|
Parameters
|
|
|
|
Name
|
Constraints
|
Description
|
|
|
controller
|
None
|
The component that handles the resource request.
|
|
|
language
|
IsNotEmptyStringRouteConstraint
|
A lowercase two-letter code derived from ISO 639-1 that specifies the language to localize resources in.
|
|
|
country
|
IsNotEmptyStringRouteConstraint
|
An uppercase two-letter code derived from ISO 3166 that specifies the country to localize resources in.
|
|
|
year
|
IsYearRouteConstraint
|
The year for the specified date-time, including the century. If the year is less than four digits in length, then preceding zeros are appended as necessary to make the displayed year four digits long.
|
|
Examples
|
|
|
|
Example
|
Description
|
|
|
/posts/es-MX/2008
|
Returns all blog posts published in 2008 that are localized to use Spanish - Mexico.
|
|
|
/posts/es/2008
|
Returns all blog posts published in 2008 that are localized to use Spanish.
|
|
|
/posts/2008
|
Returns all blog posts that published in 2008 that are localized to use locale specified by the Accept-Language HTTP header or fallback neutral language.
|
| |
|
|
|
|
|
Route
|
/{controller}/{language}-{country}/{startDate}-{endDate}
|
|
Name
|
ResourcesByDateRange
|
|
Description
|
Manipulates the representation of the resource(s) handled by the controller that are constrained by the specified date range.
|
|
Parameters
|
|
|
|
Name
|
Constraints
|
Description
|
|
|
controller
|
None
|
The component that handles the resource request.
|
|
|
language
|
IsNotEmptyStringRouteConstraint
|
A lowercase two-letter code derived from ISO 639-1 that specifies the language to localize resources in.
|
|
|
country
|
IsNotEmptyStringRouteConstraint
|
An |