When you talk about the Resources a service exposes, you have to think VERY VERY broadly. “Resource” is just a euphemism for “information”. In the 80s we would have called it “data”.
Because a service is capable of providing so much information, it’s almost impossible to define what should be exposed if you’re just sitting on the server side looking out. Rather, you need to sit on the client’s side, and start carving out the demands that will satisfy the client’s needs.
Obviously there will be some guesswork on the server side, trying to anticipate needs. But I think there’s a real danger equating “Data Model === Resources,” or “Database Schema === Resources.” I lot of the REST conversations I’ve seen get tangled up because they are trying to constrain their Resource definitions too tightly, and end up restricting what the client can get at, making the client make lots of calls to get what they could get at once. Or they go the other extreme, and make Resource definition so incredibly broad that every Resource in the system meets every need that we could possibly anticipate from the client, making every response huge, bloated documents that take a long time to code, maintain, and support the bandwidth for.
For some reason, it’s not acceptable to provide a closely-tailored API call (i.e. a Resource) that will greatly improve the efficiency of an important client.
I think the agile model of “program closely to the requirements” applies here. Define your resources closely to the requirements of the client. Just be flexible & responsive if those requirements change.
BTW The post that got me off on that tangent (again) is much broader and much more interesting and articulate:
The same author has a wonderful post later where he describes a hypermedia document as an event filter, by which a client can filter incoming events against hypermedia to figure which events should be passed on to the server, and how.
…hypermedia is an event filter. In a RESTful system, input events from the user are processed by the client according to the controls specified by the currently-loaded hypermedia document. These controls determine if an event is simply dropped, transforms the document or application state in some way, or is translated into a request on the uniform interface for a new document to be loaded. Embedding controls in the data transfered to the client offers performance benefits over a client-server model that transmits all events to the server, and visibility benefits over a mobile-code architecture where downloaded code processes events. Controls are more than links; hypermedia is more than linked data.