URI Parameters for Resource Naming

by Subbu Allamaraju on June 1, 2009

Here is an example that we are trying to grapple with. Say, a server is providing two URIs.


Of these, the purpose of the second URI is to refer to a portion of the resource identified by the first URI. The server could use query parameters or matrix parameters. That is just an implementation detail. Let us assume that these URIs are opaque to the client and the server is using links to convey them to clients.

This usage is fairly common with GETs. However, most in the REST community (us included) discourage such URIs with PUT and DELETE. Why so?

Here is another example that may influence your answer.


When it is okay for a client to GET the first name via the second URI, why is it considered bad to allow it to update the first name resource by using the same URI?

Would you prefer changing the above URIs to the following?


If so, why?

Thanks in advance for sharing your views.

{ 17 comments… read them below or add one }

Josef Finsel June 1, 2009 at 6:29 pm

I think that certain situations make it bad. Take something with a more generic filter, like http://www.example.org/customers;region=north. If the URI is opaque then I can post a new customer to http://www.example.org/customers. But should I be able to post a new customer that belongs to the east region to http://www.example.org/customers;region=north? I will grant you that there is nothing technically preventing such a thing but as a human developer I would expect that it would throw a 400 since the region doesn’t match the one associated with the URI.

Alternately, what if I wanted to PUT one of the rows I got back from http://www.example.org/customers;region=north with a change of region, from north to south? Again, computers may not care but, as a developer, I would expect that I would need to PUT to http://www.example.org/customers because what I’m posting is invalid with what is getting returned.

Does that make sense?


mike June 1, 2009 at 10:13 pm

The point you are making is that edit against the *filtered* resource might result in a response that drops the some of the edited content from the filtered resource, right?


durdyodhan June 2, 2009 at 7:48 am

Yes , but I don’t think that is a good reason — you will run into a whole another mess. What you can do is give a redirect when someone asks to PUT on the filtered resource. This is upto the developer – whether you want edits to take place from one place or from multiple places. Again, REST is an interface model and its upto you to decide the interface; based upon use case scenarios. I see nothing wrong in the scenario Josef talked about.


Andrei Filimonov June 1, 2009 at 6:58 pm

Second option may seem more logical. It would clearly identify firstname as a resource in the user context. It would also allow using PUT in addition to GET. However, it is not clear what is the meaning of POST and DELETE in this case. Therefore, both options are problematic as they break basic REST principles and force you to specify what HTTP operations are allowed.

A cleaner but not necessarily simpler way to deal with the problem is to define a separate resource representing a view of User:


It will work for Read Only views in all scenarios but may impose some limitations on mutable views (i.e allowing CRUD operations). Dealing with mutable views is generally a challenge and RESTful architecture is not an exception here.


subbu June 1, 2009 at 7:11 pm

Which REST principle is the first example breaking?


Andrei Filimonov June 2, 2009 at 11:32 pm

The first example have number of problems.

1. If you are using matrix parameters you are essentially defining a new resource. You can derive the fact that this a subset of original resource by looking at URI. This breaks the principle that URI has no other meaning beyond uniquely identifying the resource. However, the counter argument is that there is nothing wrong with using some resource naming convention. This may be a valid point only if you treat subset as a separate resource.

2. Using query parameter is worse: you use them as if to request a different resource representation when in fact you return a different resource (for all practical purposes).

3. Generally dealing with resource views introduces a great deal of design ambiguity which has to be resolved on a case by case basis. It is akin to mutable views in the database world with pretty much same challenges.


Stefan Tilkov June 1, 2009 at 7:58 pm

Without any justification whatsover in any standard, let alone the REST thesis, I somehow feel that …/firstname identifies a resource that can be updated, while …;select=firstname doesn’t.


subbu June 1, 2009 at 8:41 pm

Stefan – would it be fair to say that this view is based on a hunch that the server developer has not paid enough attention to resource and URI design, and is possibly abusing URI parameters?


Ross Duncan June 2, 2009 at 11:49 am

I would agree with Alexei and Stefan that /firstname ‘more clearly’ identifies a resource (whatever that means) than utilising query paramaters for this information.

As an aside, some discussion on the architectural costs of abusing URI parameters in this way would make pretty interesting reading


subbu June 2, 2009 at 1:47 pm

Ross – thanks for the comments. Could you elaborate on what you see are the “architectural costs” of a server abusing URI parameters – particularly for machine-to-machine applications?

I am working on a separate post to give some background on questions like these.



Andrei Filimonov June 2, 2009 at 11:45 pm

Both /firstname and ;select=firstname define resources but these resources are different. /firstname defines firstname as a first class resource (whatever that means). Its relationship to some-resource is clearly defined. ;select=firstname defines a resource that is derived from some-resource but this is a separate resource nevertheless. The relationship to some-resource can only be figured out from the URI name though. In theory, both /firstname and ;select=firstname should support all CRUD operations which in practice may not have much sense or may be problematic to implement.


Hedge July 31, 2009 at 9:21 am

Thanks for some very interesting and thought provoking comments?

“The relationship to some-resource can only be figured out from the URI name though.”

I have been think about URI’s in the terms communicated by the ‘rel’ property of the link. So I would expect that the ‘derived’ nature of a reouces would be specified by the rel property, baybe something like: current or subsection or related

Would be interesting to hear your’s and Subbu’s thoughts.
Especially I’m puzzled why none of these comments mention the role of ‘rel’ations or media types in disambiguating a URI. Example I’d expected that in Josef’s scenario that rel or media type would indicate when a ‘bad situation’ was the current state of the application.

Given no comments here mention these two components I’m beginnign to think I’ve misunderstood the nature and intent of ‘rel’ation and media type in communicating state vs inferring state from the URI format….


Dave C June 2, 2009 at 2:26 pm

a PUT to a URL as in your second example seems very logical and, moreover, useful.

Suppose the resource is quite large in terms of # of fields. It makes no sense to require a PUT of the entire resource with one field changed.

I would agree that POST and DELETE are somewhat ambiguous and might be avoided.


mike June 2, 2009 at 3:11 pm

Dave C:

Are you thinking that, in the case of the second example, the PUT only includes the values identified in the filter parameter?


Ross Duncan June 2, 2009 at 4:10 pm


“Could you elaborate on what you see are the “architectural costs” of a server abusing URI parameters – particularly for machine-to-machine applications?”

I guess Im looking for a more exhastive list of reasons why URIs that rely on query parameters to identify a resource are second class citizens to those that do not. I think they look ugly, and feel bad, but hey, a machine client might be a little less subjective

One such angle could be to consider if intermediaries or browsers make a distinction between the two sorts of URIs discussed above when caching. Apache mod_cache for example seems to be configurable in this area. (http://httpd.apache.org/docs/2.2/mod/mod_cache.html). If a resource can only be accessed using a query parameter laden URI, and an intermediary deems not to cache such, then obviously performance drops away.


Hedge July 30, 2009 at 8:11 am

After reading Subbu’s InfoQ article “Describing RESTful Applications” I’d started to convince my self that in complex or ambiguous situations (if not always), that the hyperlink providing the URI should provide a relation:
“A link has at least two properties – a URI, and a relation” and again from that article:
“the relation describes the type or kind of the link”

So I had expected that the answer to the question:
“When it is okay for a client to GET the first name via the second URI” should be conveyed in the relation detail of the link that provided each of the URIs. No?

Maybe I’m abusing the intended use of relations?


Basavaraj December 2, 2011 at 5:53 am


Late, but in my analysis (to original question from Subbu) is that, characters “?”, “;”, “#” are considered as the path terminators (URI path is considered to end at these characters) hence using them in URIs for parameter, make the URI non-RESTful

Hence we should not have such parameters part of URIs, if it so needed make it part of the the URI itself

So i will rewrite the second URI as these



or as


People please comment and correct if my understanding is wrong



Leave a Comment

Previous post:

Next post: