URI Templates

A URI template is a string that is used to identify the correct resource handler. The routing algorithm uses the resource path and checks it against all attached URI templates to call the resource handler of the best matching template.

The rest library supports 3 kinds of URI templates:

1. Static Templates

   This case is used when the resource path must match exactly to select a resource.

   For example there may be two manufacturer histories attached to the router:

   ->attach( iv_template = '/cars_history/maserati' iv_handler_class = 'CL_RESOURCE_MASERATI' ).

   ->attach( iv_template = '/cars_history/ferrari' iv_handler_class = 'CL_RESOURCE_FERRARI' ).

   So when the resource path is /cars_history/ferrari the handler CL_RESOURCE_FERRARI is called.

2. With URI Attribute

   URI attributes allows more flexible URI routing. With the pattern '{' AttributeName'}' one or more attributes can be inserted into the template to match not only an exact resource path but any kind of characters. This is especially useful when having a resource handler which handles a collection.

   For example there may be a cars resource handler registered with the following attach command:

   ->attach( iv_template = '/cars_history/{MANUFACTURER}' iv_handler_class = 'CL_RESOURCE_MASERATI' ).

   So any any of the following resource paths will match:

   '/cars_history/ferrari'

   '/cars_history/maserati'

   '/cars_history/porsche'

   ...

   but also '/cars_history/1325'.

   During routing, the variable part which matches { MANUFACTURER } can be obtained from the REST request with methods GET_URI_ATTRIBUTE and GET_URI_ATTRIBUTES with the name AttributeName used in the braces.

3. With URI Regular Expression Attribute

   Instead of matching any character, it is also possible to use a regular expression in the URI template. These regular expressions are written in the form '{' AttributeName : Regex '}' where Regex is an ABAP regular expression matching zero or more characters.

   URI templates with and without regular expressions can be mixed.

   Take the sample above with the following URI template.

   ->attach( iv_template = '/cars_history/{ID:[0-9]+}' iv_handler_class = 'CL_RESOURCE_MASERATI' ).

   So any of the following REST resource pathes will match:

   '/cars_history/0'

   '/cars_history/1'

   '/cars_history/2'

   ...

   but NOT

   '/cars_history/maserati'

   because maserati contains not only digits;

   it does also not match for the resource path

   '/cars_history/maserati'

   because the ID of a car entity must not start with an alphabetic character.

   Another example:

   ->attach( iv_template = '/test/{path:.*}' iv_handler_class = 'CL_RESOURCE_TEST' ).

   Will match any resource path starting with '/test/' whereas the URI attribute path will contain every character after '/test/'. For '/test/segment1/person/1' the URI attribute path will be 'segment1/person/1'

URI Templates Collisions

There may be circumstances where two or more URI templates match the same resource path. For example, the patterns '/cars/{ ID }/color' and '/cars/{ ID }/{ TYRE } will both match resource path '/cars/1/color'.

To solve this, the REST library sorts all matching URIs as defined in the JAX-RS Version 1.1 specification:

1. Sort all matching templates:

   - Use as primary key: the number of literals in the template descending (without the braces)

   - Use as secondary key: the number of variables descending

2. Use the first match.