Detail question on REST URLs

Question

This is one of those little detail (and possibly religious) questions. Let's assume we're constructing a REST architecture, and for definiteness lets assume the service needs three parameters, x, y, and z. Reading the various works about REST, it would seem that this should be expressed as a URI like

http://myservice.example.com/service/ x / y / z

Having written a lot of CGIs in the past, it seems about as natural to express this

http://myservice.example.com/service?x=val,y=val,z=val

Is there any particular reason to prefer the all-slashes form?

Answer 1

The reason is small but here it is.

Cool URI's Don't Change.

The http://myservice.example.com/resource/x/y/z/ form makes a claim in front of God and everybody that this is the path to a specific resource.

Note that I changed the name. There may be a service involved, but the REST principle is that you're describing a specific web resource, named /x/y/z/.

The http://myservice.example.com/service?x=val,y=val,z=val form doesn't make as strong a claim. It says there's a piece of code named service that will try to do some sort of query. No guarantees.

Answer 2

If the resource is the service, independent of parameters, it should be

http://myservice.example.com/service?x=val&y=val&z=val

This is a GET query. One of the principles behind REST is that you GET to read (but not modify!) the resource; you can POST to modify a resource & get a response; you can PUT to write to a resource; and you can DELETE to remove a resource.

If the resource specific with those parameters is a persistent resource, it needs a name. You could (if you organized your webservice this way) POST to http://myservice.example.com/service?x=val&y=val&z=val to create a particular instance of the service and have it return an ID to name this instance, e.g.

http://myservice.example.com/service/12312549

then use GET/POST/PUT/DELETE to interact with that instance.

Answer 3

Query parameters are rarely "cool". Take a look at the Google Chart API. Should that use a /full/path/notation for all of the fields? Would each URL be cool if it did?

Query parameters are useful. Optional fields can be omitted. New keys can be added to support new functionality. Over time, old fields can be deprecated and removed. Doing this is clumsier with a /path/notation .

Quoting from http://www.xml.com/pub/a/2004/08/11/rest.html

URI Opacity [BP]

The creator of a URI decides the encoding of the URI, and users should not derive metadata from the URI itself. URI opacity only applies to the path of a URI. The query string and fragment have special meaning that can be understood by users. There must be a shared vocabulary between a service and its consumers.

This sounds like query strings are what you want.

One downside to query strings is that the are unordered. The GET ending with "?x=1&y=2" is different than that ending with "?y=2&x=1". This means the browser and any other intermediate systems won't be able to cache it, because caching is done based on the full URL. If this is a concern, then generate the query string in a well-defined order.

Answer 4

A URL with slashes like /x/y/z/ would impose a hierarchy and is not suited for the exact case of just passing three parameters.

If, like you said, x y z are indeed just parameters and the order is not important, it would be more RESTful to use semicolons:

http://myservice.example.com/service/x;y;z/

If your "service" however is just an algorithm that works the same with different parameters, there would also be nothing unRESTful with using ?x=val format.

Answer 5

While constructing URIs this is the priniciple I follow. I don't know whether it is perfectly acceptable in all cases

Say for instance, that I have to get the details of an employee, then the URI will be of the form:

GET /employees/1/ and not GET /employees?id=1 since I treat every employee as a resource and the whole URI "employees/{id}" is used in identification of the resource.

On the other hand, if I have algorithmic operations that do not identify a specific resource as such,but merely require inputs to the algorithm which in turn identify the resource, then I use query strings.

For instance GET /employees?empname='%Bob%'&maxResults=100 might give me all employees whose names have the word Bob in them, with the maximum results returned by the query limited to 100.

Hope this answers your question

Answer 6

First of all, defining URIs as part of your API violates a constraint of the REST architecture. You cannot do that and call your API RESTful.

Secondly, the reason query parameters are bad for non-query resource access is that they are generally not cached. It is also a violation of HTTP standards.

Answer 7

URIs are strictly split into a hierarchical part (the path) and a non-hierarchical path (the query), and both serve to identify the resource

Tthe URI spec itself (RFC 3986) clearly sets the path and the query portion of a URI as equal.

Section 3.3:

The path component contains data [...] that along with [the] query component serves to identify a resource.

Section 3.4:

The query component contains [...] data that, along with [...] the path component serves to identify a resource

So your choice in using x/y/z versus x=val&y=val&z=val has mainly to do if x, y or z are hierarchical in nature or if they're non-hierarchical, and if you can perceive them as always being hierarchical or non-hierarchical for the foreseeable future, along with any technical limitations you might be having on selecting one over the other.

But to answer your question, as others have noted: Neither is more RESTful than the other, since they both end up identifying a resource.