RESTFul Flat Hierarchy vs. Dynamic Hierarchy for Search Resource

Question

We are creating a REST API and we currently have two approaches for defining the resources.

Basically we have Patients, Studies and I

Answer 1

Flat and hierarchical URIs could be both RESTful. The problem is elsewhere. Being RESTful suppose that URIs are identifiers of resources.

What resource is identified by /wepapi/patients/0/studies/12/images? The images of studies 12.

Is it really a bad identifier? Not really.

Could it be better? Definitely:

• wepapi (the way you get a representation of the resource) has nothing to do with the abstract resource. The most RESTful approach would be to have the same URI for different concrete "representations" of the same abstract resource (see HTTP Accept headers for more information).
• patients/0is not needed to identify those images. You might think that it would be cool for client software to get this datum by parsing the URI, but... they are not supposed to do that. URI are said to be "opaque".

What resource is identified by /search?q=imageName:mountain? The images that are named "mountain".

Is it really a bad identifier? Not really. Could it be better? Definitely:

• search looks like a verb, which should raise a lot of warnings in a RESTful designer mind. In a way, we could say that the URI identify "a search" or "search results" (a noun and not a verb), but it is safer to consider that it identifies "images".

Last but not least, choosing between /studies/12/images and /images/?studies=12 in order to be "coherent" with either /studies/12 or /images/?name=mountain is purely a software design choice. Take the solution that will be the more elegant for your application. It has nothing to do with REST, since URIs are not supposed to be hacked (remember, they are supposed to be "opaque"). The links between URIs are in their representations (JSON, XML, HTML...), not in their structure.