REST API having same object, but light

Question

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

• full version: http://api.domain.com/myobject/{objectId}
• light version: http://api.domain.com/myobject/{objectId}?filter=light

2nd case

• full version: http://api.domain.com/myobject/{objectId}/details
• light version: http://api.domain.com/myobject/{objectId}

3rd case

• full version: http://api.domain.com/myobject/{objectId}?full=true
• light version: http://api.domain.com/myobject/{objectId}

4th case ?

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

Thanks.

Answer 1

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.