Question

I am currently adding a REST API over http to an online service and I am confronted with a very simple problem for which I cannot find an answer that satisfies me:

I have mainly 2 resources: ‘user’ and ‘reports’, as you would have guessed reports are associated to users (to one and only one, = foreign key in my db)

Anyway I have this url mapping for GET :

• mywebsite/api/users/{id} : returns a user and related information, or a list of users if id is not present
• mywebsite/api/report/{id} : returns a report and related information, or a list of reports if id is not present

Now I would like to get the reports for a specific user, my way of doing it now is to add an optional parameter to the GET method for reports: ?username={username} and if it is present, I am filtering the results to return only the reports for this user.

I can’t help but think something is wrong… if I start doing things like this I will have my methods handling GET full of if/else looking for missing parameters…

Other solutions I I thought of are:

• incorporate the reports in the resulting GET on mywebsite/api/users/{id} but I have many many reports so in the end it will become really bad…
• map another url just for this function, but it just doesn’t feel right…

I am just getting the grips of this REST thing, I like the concept but a little explanation on this matter would really help me understand it better.

Thanks

Edit:

It seems I have hit a common problem in the REST world, I have tied my resources to a model. If you tie a resource to a model you end up having trouble with aggregate attributes.
Some guy describes this error here http://jacobian.org/writing/rest-worst-practices/ but I have yet to understand how to manage that as he said…

fyi I am using django/piston but this question should be answerable regardless of any language.

Answer 1

I can’t help but think something is wrong…

The only thing you’re doing wrong is thinking that your URI structure makes your application more or less RESTful. The original REST literature never says that query strings are bad. People tend to get hung up on URI structure and seem to think that your URIs must be structured a certain way to be considered RESTful. There is nothing wrong with using ?username=<username>. A URI is just an ID (though some can be more human friendly than others).

Bottom line: don’t get hung up on how your URIs look. There are much more important things to focus on (promoting hyperlinking/hypermedia, sticking to a uniform interface – typically HTTP, cacheability, etc.).

This may be a big of a digression but, as for your comment about the coupling of resources to models, you’re still okay. If you do go the /reports/ID/user route, just think of ‘user’ as a relationship name on your reports model. Surely your model defines the relationship between a report and a user. You can just parse the last part of your URI so that it matches the name of this relationship. In the case of one to one relationship like you describe its always a good idea to also set the Content-Location header to match the canonical URI of the user.

For example. Say report 123 belongs to user 1. You now have two ways of referring this user:

http://example.com/reports/123/user
http://example.com/user/1

For the first URI, it would also be a good idea to set Content-Location: http://example.com/user/1 header