I have a rest service that is essentially a proxy to a variety of other services. So if I call
GET /users/{id}
It will get their user profile, as well as order history, and contact info, etc… all from various services, and aggregates them into one nice object. My problem is that each call to a different service has the potential to add time to the original request, so we would rather not get ALL the data ALL of the time if a particular client does not care about all of the pieces.
A solution I have arrived at is to do something like this:
GET /users/{id}?includeOrders=true&includeX=true&includeY=true...
That works, and it allow me to do only what I need to, but it is cumbersome. We have added enough different data sources that there are too many parameters for that style to be useful. I could do something similar with a single integer and a bitmask or something, but that only makes it harder to read, and it does not feel very Restful.
I could break it down into multiple calls so they would need to call /users/{id}/orders and /users/{id}/profile separately, but that sort of defeats the purpose of an aggregating proxy, who’s purpose is to make clients jobs easier.
Are there any good patterns that can help me return just enough data for each client, without making it too difficult for them to filter and select what they want?
2
As Aaron McIver has already noted, a RESTful architecture is mainly intended to leave the clients ask for they want (service segregation). It should be your client (a traditional web page, an AJAX page, a GUI-less WS client) to decide which information sources it wants to use and call the corresponding servers. It should be your client to collect data, organize it and display it to the end user.
There is nothing wrong in having one or more convenience proxy server that aggregate data, when this data is commonly used in this aggregated way, but this should be considered just this: a convenience method, not the standard way to go. The reason for this is what you are experimenting now: the external interface (the side to the end user) suffers a combinatory complexity explosion and rapidly became unmaneagable.
So you should leave your client decide if it wants to query one or more aggregated-data server or the original raw data sources. You should leave the client to assemble the data and display it. Please note that you can have more than one proxy server, if this makes sense in your case.
Put aside this, consider as well that you can make a good use of cache and temporary tables (database “views”) to supply the proxy server with ready-to-use, partially-digested data.
1
I would suggest returning your minimum subset of data with links to the other related data.
If you currently have something like the following:
<user>
<id>1</id>
<defects>
<defect id="100" ... />
<defect id="101" ... />
<defect id="102" ... />
</defects>
<stories>
<story id="10" ... />
<story id="11" ... />
</stories>
</user>
You could turn that into:
<user>
<id>1</id>
<defects>
<link rel="defects" href="http://example.org/users/1/defects">
</defects>
<stories>
<link rel="stories" href="http://example.org/users/1/stories">
</stories>
</user>
Then your client could follow the links to get the data that it cares about.
Alternatively, you could treat the options as a single sub-resource of users, and depending on how you’re able to respond to certain requests, it could be done in a single method.
To continue my example, you might accept the following URIs:
GET /users/{id}/defects
GET /users/{id}/stories
GET /users/{id}/defects_stories
GET /users/{id}/stories_defects
In Spring we could accomplish this with something like:
@RequestMapping(value = "/users/{id}/{options}", method = RequestMethod.GET)
public @ResponseBody String get(@PathVariable Long addressId, @PathVariable String options) {
// parse options, retrieve data, etc
return "your xml";
}
Based on your additional comments, this might be the best approach, if you can handle it without adding too much complexity. I would avoid Robert Harvey’s suggestion of using true/false parameters separated by slashes, because it abuses the hierarchical meaning of URIs; plus it’s even less readable than your current solution.
Ultimately, there’s nothing in REST against using URL parameters (since REST isn’t specific to HTTP); see this related SO question about URL parameters & REST.
2