Matrix URIs in RESTful API

Matrix URIs

Matrix spaces and Semicolons

It is maybe obvious to note that there are many, many hierarchical systems. An interesting analogy with a hierarchical power is, in a programming language, a sequence of parameters supplied to a command or a procedure. For example, in some languages a procedure may take positional parameters which may be optional so that any parameters from a certain point on may be omitted. This syntax can be compared with a hierarchical slash separated URL path. This is an interesting analogy because looking at the alternative representation for procedure parameters which consists of a list of procedure name and value pairs. This leads us naturally to a discussion of the use of the semi-colon in URLs and thematrix syntax. Just as the slash separated set of elements is useful for representing a tree, so a set of names and equally significant parameter can represent a space more like a (possible sparse) matrix. In this case navigation to "close" locations is done by varying one or more parameters which form the dimensions of the matrix. This is the purpose of the a=b; parts of URL syntax which was added later in the URL's history. The initial need was to put qualifiers onto URLs which were themselves hierarchical.

The analogy with procedure call holds still when looking at combined forms: The hierarchical part of the URL is paused first, and then the semi-colon separated qualifiers are paused as indicating positions in some matrix. As an example let's imagine the URL of an automatically generated map in which the parameters for latitude, longitude and scale are given separately. Each may be named, and each if omitted may take a default. So, for example,

 //moremaps.com/map/color;lat=50;long=20;scale=32000

might be the URL of an automatically generated map.

Parsing matrix URLs: issues

How should one pause relative URLs in this context? Clearly the most convenient is to be able to select a similar map of a different scale simply by specifying ;scale=64000 as a relative URL. The pausing of the syntax has not been well defined in the URL circles and to my knowledge, has not been consistently used. So, in January 1997, whereas this might be a good idea, it is not currently implemented. However, this is the natural way to pause relative URLs which contain named parameter values. Another unresolved question is whether the order of such parameters should be significant, as logically expressing the same set of parameters in a different order normally has the same semantics. When a relative URL starts with a semi-colon, one can imagine the significance of that to be that all parts of the URL other than the parameters remain unchanged; that the parameters which have not been specified in the relative URL remain unchanged and that the parameter given in the URL takes its given value in place of any GET value in the original URL. Clearly, when adding another parameter value, this does not allow one to specify where it takes its place in the set of parameter values, which then implies that the order of the parameters must be immaterial. There is also the question of how to logically, in a relative URL, remove a parameter, but this could clearly be done if the convention is that a missing parameter has the same significance as a present perimeter with the now string as its value. It is not at all evident that this is what is most wise, so perhaps a special syntax should be used for deleting perimeters.

Parsing matrix URLs

Note: relative Matrix URLs are notgenerally implemented so this is just a theoretical discussion.

It is only sensible for relative URls which start with ";" to take a set of attribute values which are different from those of the base URL. This implies.

  1. attributes can only occur once (unless you have a syntax for identifying and removing a particular occurrence, which is very messy) and
  2. there must be a syntax for removing an attribute, hopefully distinguishing a removed attribute from one whose value if the empty string; and.
  3. attributes are unordered.
So, by these rules, relative to
 //moremaps.com/us/ma/cambridge;scale=50000;roads=main 

or the equivalent

 //moremaps.com/us/ma/cambridge;roads=main;scale=50000 

relative URLs would be parsed as follows.

Relative URIShould be interpreted as

//moremaps.com/us/ma/cambridge;scale=50000;roads=main
;scale=25000 //moremaps.com/us/ma/cambridge;scale=25000;roads=main
;roads //moremaps.com/us/ma/cambridge;scale=50000
;roads= //moremaps.com/us/ma/cambridge;scale=50000;roads=
;rivers=all //moremaps.com/us/ma/cambridge;scale=50000;roads=main;rivers=all
Next Recommended Reading API Endpoint Naming Best Practices