6

Consider a user (/users/{id}) which has a name and multiple locations (/users/{id}/locations).

When I request a user (/user/{id}), should that user be represented fully--its id, name and locations--or should locations only be returned on a separate request? For example, which JSON DTO would you expect on a request for user with id=123 (/users/123):

1) { "id":123, "name":"Peter", "locations":[{"id":1, "name":"Chicago"}, {"id":2, "name":"New York"}] }

2) { "id":123, "name":"Peter", "locations":[{"id":1}, {"id":2}] }

3) { "id":123, "name":"Peter", "locations":[1, 2] }

4) { "id":123, "name":"Peter" }

Is this more subjective, pushing and pulling between size of the DTOs and requests required in the typical use-case? I'm inclined to simply include all of the relevant data (1), but I'm not certain that's better than just requiring developers to make multiple calls to an API to get all of the data they actually want.

M. Herold
  • 684
  • 1
  • 7
  • 18
  • 1
    Any reason why you wouldn't add a query parameter to turn on/off listing sub-element collections? That wouldn't be dissimilar to adding a ?format={json|xhtml} for adjusting the format of the output... – ScottCher May 02 '12 at 17:01
  • Mostly because of development time; I don't want to introduce unexpected or unnecessary additions. I just want to do things "right" or at least in a reasonable, quick fashion. – M. Herold May 03 '12 at 21:22

3 Answers3

3

To be RESTful you don't necessarily have to return the full representation of the resource You do however want to enable hypermedia as means to get/set all the information the user of your API needs (Hypermedia as the engine of application state - a.k.a. HATEOAS)

To satisfy that you can either use the suggestion by @bowmanb to put a URI for all the locations or add individual URIs for each of the locations. You probably want to add additional URIs for other options of doing something with the resource.

There's a good article on HATEOAS by Jim Webber, Savas Parastatidis & Ian Robinson called "how to GET a cup of coffee"

Arnon Rotem-Gal-Oz
  • 25,469
  • 3
  • 45
  • 68
2

I am a newbie in this world, but I am building a restful api and facing exactly the same issue. My initial work has been toward including everything - so my results look like your option (1). In fact, I go a little further and included a URI with each object so that, in theory, the response can be navigated by a sufficiently intelligent client.

Having said that, I have found that one particular attribute of my equivalent to your "user" object is enormous. It doesn't seem to impact performance, but it seems to me that no client would want all that information about that particular attribute - most clients would just want the id and name. So, I will be modifying my default approach for that attribute.

Bottom line - in my newbie opinion - is that the decision is driven by the expected usage of your clients - what would the client want to see?

user229044
  • 232,980
  • 40
  • 330
  • 338
Richard Berger
  • 247
  • 2
  • 11
1

There should be some way for a client to determine how to find a user's locations. So I would rule out number 4.

If you are concerned about the size of your response, I believe it would still be RESTful to include just the URI to a user's locations:

{ "id":123, "name":"Peter", "locations":"/users/123/locations" }
anon
  • 4,163
  • 3
  • 29
  • 26
  • Then, presumably, your collection of locations would be individual URI references to each location? eg, /locations/{locationid} – ScottCher May 02 '12 at 17:00
  • That's what I was thinking. If a user's locations are important to the service, and size of the response is not a concern, I'd include everything in the /users/{id} response, including the URI (as @Arnon Rotem-Gal-Oz said). `{ "id":123, "name":"Peter", "locations":[{"id":1, "name":"Chicago", "uri":"/users/123/locations/1"}, {"id":2, "name":"New York", "uri":"/users/123/locations/2"}] }` – anon May 02 '12 at 18:00