The REST folk disagree with you. If the picture and the contact information are different representations of the same resource (which is not that much of a stretch conceptually), then they absolutely should be reached at the same URL. At that point, the only way you have left to distinguish what you want is the mime type.

Out of curiosity: how do the REST folk feel about differentiating between resources with urls like /user/1.json and /usr/1.html ? That has been pretty popular, from the little I've seen, and has the advantage of being GET-able with a browser, where header modification is not.

You should use content negotiation for this. The client should have an Accept header that specifies what it wants (which could be "application/json" but really should be something that tells you more about the contents than simply how it can be parsed, such as "application/vnd.mything.MyResource+json" which would be documented in your API with what fields it contains and what it means etc.).

You should also question whether you really need multiple representations for each resource -- in many cases, it's more trouble than it's worth to automatically generate, say, both JSON and XML responses, since it just divides your attention to creating sensible serializations for your API.

If you expect to have clients which cannot modify the headers of their requests, you can support fallbacks like specifying the Accept header in a query parameter. Putting it in the actual URL though is doing a disservice to fully compatible HTTP clients, though.

But if JSON is so inherent to the resource that content negotiation doesn't even matter, it can be fine to include that in the URL, as you might include descriptive filename extensions like ".png" or ".wav" in a URL.

That is still a case of using two URIs to refer to the same resource. If you use one URI per resource, URIs (and bookmarks) can be shared between clients dealing with different media types. Suffixed URIs require mangling to request a different media type.

Clearly it is a pragmatic trade-off and is popular (Google and Twitter do it). The correct answer will be arrived at by considering the total architecture of your application.

As soon as you decide to create two URLs such as /user/1.json and /usr/1.html you are creating two distinct resources. The litmus test for determining if two URLs refer to the same resource is you do a GET on both and only one of them returns a 200 the other returns a 303 with the Location header set to the URL that returned a 200.

That's a good reason to differentiate by header (plus no .jpg vs .jpeg shenanigans in the url). Though I can't say I've ever heard of it being used... I'll have to keep it in mind if I'm ever architecting something that anticipates many different kinds of clients in a large API, however.

Not sure how all REST folk feel, but Roy doesn't have any problem with using the convention of file extensions to indicate resources with different formats. http://tech.groups.yahoo.com/group/rest-discuss/message/1396...

Well, to be clear, he says you should certainly use the Accept header, and if you want to be nice you should provide the formatted URLs as well.

Yeah, but he's explicitly saying that they are different resources with differing types, not the same one with differing types.

Wrong in theory, inevitable (or at least pragmatic) in practice.