14

We are building a REST API and we want to return the same object, but one call is a 'light' version (without all the field)

what is the best practice ?

1st case

2nd case

3rd case

4th case ?

Any link to a documented resource of a REST API is welcome !

Thanks.

1
  • 1
    in the 3rd case you might mean either full=false or swap the urls.
    – jfs
    Commented Oct 21, 2011 at 14:53

2 Answers 2

11

This should be handled through content negotiation, that's what its for. Content negotiation is how a client can request which representation of the resource it wants to see. Consider the case of a picture: image/x-canon-cr2, image/jpeg, image/png.

Ostensibly all the same image, but in different formats.

So, this is the mechanism you really want to use for a "lite" version of your resource. For example you could use:

  • "application/xhtml+xml" for the main version
  • "application/xhtml+xml; lite" for the for the light weight version

So, for a full resource:

GET /resource
Accept: application/xhtml+xml

For a light version

GET /resource
Accept: application/xhtml+xml; lite

For either, but preferring the lite version:

GET /resource
Accept: application/xhtml+xml;lite, application/xhtml+xml

(the more specific specifier, i.e. the one with ;lite, has higher priority over the normal applciation/xhtml+xml.)

If you will take either, but prefer the full version:

GET /resource
Accept: application/xhtml+xml;lite;q=0.1, application/xhtml+xml

Those without a quality factor default to 1.0, so 0.1 is less than 1.0 and you will get the full version if available over the lite version.

Addenda:

The q factor on Accept is effectively used to show the preferences of the client. It is used to prioritize the list of media types that the client accepts. It says "I can handle these media types, but I prefer a over and b over c".

A JPEG vs a PNG is no different than the lite vs full version. The fact that a JPEG looks anything like the original PNG is an optical illusion, the data is far different, and they have different uses. A JPEG is not "lower quality", it's different data. It's "missing fields". If I want, say, the image size, the JPEG will give me that information just as well as a PNG would. In that case, it's quality is adequate for the task. If it wasn't adequate, then I shouldn't be requesting it.

I can guarantee that if I have a client that can only process PNG and ask for a JPEG, then that program will not "work equally well" with it. If my son wants Chicken Fingers and I give him Cream of Spinach, there are going to be issues, even though both of those are representations of the the resource /dinner.

The "application/xhtml+xml;lite" representation is just that -- a representation, it is NOT the resource itself. That's why the word representation is used. The representations are all simply projections from the actual resource, which is some virtual entity on the server realized internally in some undefined way.

Some representations are normative, some are not.

Representations are manifested through media types, and media types are handled via Con-neg and the ACCEPT header. If you can't handle a representation, then don't ask for it.

This is a con-neg problem.

I don't know what a "media player" has to do with this discussion.

6
  • 1
    This is a somewhat fragile design for a RESTful API. Also, it is an atypical use of the ACCEPT field which normally deals alternative presentations of equivalent data (not actually changing which content is shown). Commented Oct 21, 2011 at 20:29
  • 1
    I think there's a completed valid case to be made that a JPEG is a "lightweight" version of a RAW image: it's smaller, lossy, and not a perfect representation of the resource, but adequate for many tasks. It's also easy enough for the system to reject if a client tried to force it back in to the service. Same with text/plain and text/html. Those are both perfectly acceptable uses of ACCEPT. I don't see how this is any different. Commented Oct 21, 2011 at 22:16
  • The header field definition ( w3.org/Protocols/rfc2616/rfc2616-sec14.html ) shows something like this for "quality-level" like your jpeg example. Regardless of quality level, the user still calls the same media player to display the result. The difference with "lite" is that not all fields are returned (that isn't just lower quality, it is a different dataset) and will likely not work equally well with the program making the HTTP request. If you still don't see how this is different, maybe only commenter can explain it better. Commented Oct 21, 2011 at 23:14
  • I agree with Will Hartung. This is what con-neg is for, and other mechanisms (separate URIs for the same resource, etc) are far worse solutions. Commented Oct 22, 2011 at 5:35
  • 1
    Content negotiation is for letting the server "choose the best representation of a resource based on the browser-supplied preferences for media type, languages, character set and encoding." It is about alternate presentations of the same data, not about serving-up data subsets (ranges for rows or "lite" for columuns). If the OP follows your advice, he will end-up with serious usability problems. Look at real world examples -- do you know of any stock quote server that has you pick fields of interest using content negotiation? Commented Oct 24, 2011 at 3:38
7

The 1st case and 3rd case have the advantage that one url is used for a single resource and the query string is used to request a particular view of that resource. Choosing between them is a matter of taste, but I tend to prefer a default of getting all the data and saving the options for viewing subsets.

4
  • Good point but are you paid by my coworkers to answer that ? :D I am concerned about the real REST design. I mean is there specification about that ? Commented Oct 21, 2011 at 8:41
  • 2
    The spec ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm doesn't specifically address query strings. Generally, shared data should be at the same base url so that post/put/delete will invalidate caches of both views. Also, query strings tend to be used for the kind of things a user would click on an html form (i.e. fullview or lightview) -- that provides the "state transfer" or link from one resource to the next. The root principles boil down to resource/uri matching, caching, and links (transfers) between states. Commented Oct 21, 2011 at 9:10
  • @RaymondHettinger Whether you use the path segment or a query string, you are still identifying two different resources. But you are correct in that it is just a matter of preference which you use. REST has nothing to say on the issue of URI design. Commented Oct 21, 2011 at 12:49
  • I implemented the 2nd case, but I think you are right. Also I agree with Darrel who says that REST has nothing to say on the URL format Commented Oct 24, 2011 at 15:54

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.