Detailed question on REST URLs
This is one of those little details (and possibly religious) questions. Let's say we are building a REST architecture, and for the sake of clarity, let's say that the service needs three parameters: x, y, and z. Reading the various work on 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 CGI in the past, it seems natural to express this
Is there any particular reason to prefer the forward slash form?
source to share
The reason is small, but here it is.
The cool URI does not change.
The form http://myservice.example.com/resource/x/y/z/
files a claim before God and all that is the path to a certain resource.
Please note that I have changed the name. A service may be involved, but the REST principle is that you describe a specific web resource with a name
/x/y/z/
.
The form http://myservice.example.com/service?x=val,y=val,z=val
does not claim to be so strong. It contains a piece of code named service
that will try to fulfill some kind of request. There is no guarantee.
source to share
Query parameters are seldom cool. Take a look at the Google Chart API. Should this use / full / path / notation for all fields? Would every url be cool if it is?
Query parameters are helpful. Optional fields can be omitted. New keys can be added to support new functions. Over time, old fields may become obsolete and removed. Doing this is inconvenient with the / path / notation.
Quoting from http://www.xml.com/pub/a/2004/08/11/rest.html
URI Opacity [BP]
The URI creator decides the encoding of the URI, and users should not infer the metadata from the URI itself. URI opacity applies only to the URI path. the query string and snippet have special features that can be understood by users. There must be a common vocabulary between the service and its consumers.
It looks like query strings are what you want.
One drawback of query strings is that they are unordered. Ending a GET with "? X = 1 & y = 2" is different than ending with "? Y = 2 & x = 1". This means that the browser and other intermediate systems will not be able to cache it as the caching is done based on the full URL. If this is a concern, then generate the query string in a specific order.
source to share
When constructing a URI, this is the principle I follow. I don't know if this is acceptable in all cases.
Let's say for example that I need to get employee details, then the URI will be of the form:
GET / employees / 1 / and not GET / employees? id = 1 because I am treating each employee as a resource and the entire " employees / {id}" URI is used when identifying the resource.
On the other hand, if I have algorithmic operations that do not identify a specific resource as such, but simply require input to an algorithm that in turn identifies the resource, then I use query strings.
For example, GET / employees? empname = '% Bob%' & maxResults = 100 can give me all employees whose names contain the word Bob in them, with the maximum results returned by a query capped at 100.
Hope this answers your question.
source to share
URIs are strictly divided into a hierarchical part (path) and a non-hierarchical path (request), and both serve to identify a resource
The URI specification itself ( RFC 3986 ) clearly defines the path and request portion of the URI as equal.
Section 3.3:
The path component contains data [...], which, along with the request component [], serves to identify the resource.
Section 3.4:
The request component contains [...] data, which, together with the [...] path component, serves to identify the resource
Thus, your choice to use x/y/z
versus x=val&y=val&z=val
should generally be made if x, y, or z are hierarchical in nature, or if they are non-hierarchical, and if you can perceive them as always hierarchical or non-hierarchical for the foreseeable future, as well as any technical limitations that may arise when choosing one of them.
But to answer your question, as others have pointed out, there is also no more RESTful than the other as both of them identify a resource.
source to share
If the resource is a service, regardless of parameters, it must be
http://myservice.example.com/service?x=val&y=val&z=val
This is a GET request. One of the tenets of REST is that you GET read (but don't change!) A resource; you can POST change the resource and get a response; you can PUT write to the resource; and you can DELETE to delete the resource.
If the resource specific to these parameters is a persistent resource, it needs a name. You could (if you organized your web service that way) POST before http://myservice.example.com/service?x=val&y=val&z=val
to create a specific instance of the service and return an ID to it to name that instance, for example
http://myservice.example.com/service/12312549
then use GET / POST / PUT / DELETE to interact with that instance.
source to share
First of all, defining a URI as part of your API violates a limitation of the REST architecture. You cannot do this and call your API RESTful.
Second, the reason query parameters are bad for unrequesting resource access is that they are generally not cached. It also violates HTTP standards.
source to share
A URL with a slash, for example /x/y/z/
, will overlay a hierarchy and is not suitable for the exact case of simply passing three parameters.
If, as you said, the xyz are really 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 unchanged using the format ?x=val
.
source to share