Question

I’ve been creating a RESTful application and am undecided over how I should handle requests that don’t return all entities of a resource or return multiple resources (a GET /resource/all request). Please allow me a few moments to setup the situation (I’ll try to generalize this as much as possible so it can apply to others besides me):

Let’s say I’m creating a product API. For simplicity, let’s say it returns JSON (after the proper accept headers are sent). Products can be accessed at /product/[id]. Products have reviews which can be accessed at /products/[id]/review/[id].

My first question lies in this sub-resource pattern. Since you may not always want the reviews when you GET a product, they are accessible by another URI. From what I read I should include the URI of the request that will return all review URI’s for a product in the response for a product request. How should I go about this so that it abides to RESTful standards? Should it be a header like Reviews-URI: /product/123/review/all or should I include the URL in the response body like so:

{ 'name': 'Shamwow',
  'price': '$14.99',
  'reviews': '/product/123/review/all'
}

My second question is about how the /product/[id]/review/all request should function. I’ve heard that I should just send the URL’s of all of the reviews and make the user GET each of them instead of packaging all of them into one request. How should I indicate this array of review URIs according to RESTful standards? Should I use a header or list the URIs in the response body like so:

{ 'reviews': [ '/product/123/review/1',
               '/product/123/review/2',
               '/product/123/review/3'
             ]
}

Answer 1

Your problem is you’re not using Hypermedia. Hypermedia specifically has elements that hold links to other things.

You should consider HAL, as this is a Hypermedia content type that happens to also be in JSON.

Then you can leverage the links within HAL to provide references to your reviews.