listing the resource without a file type extension is not enough for a comparison (pros and cons). How would you identify the format in the "not extension approach"? Url segment? GET parameter? It doesn't really matter, to be honest, server side it doesn't make any difference and any approach is equally valid. There are some SEO resources out there that will argue that the extension approach is friendlier to search engine bots, but it's up to you if you want to take SEO "experts" seriously or not. I don't.
–
Yannis♦Dec 15 '11 at 0:04

"Are their any problems with this approach?"? How could there be any "cons" of any kind? What are you imagining? For non-REST static files this is the norm. What would change in REST? Please amplify on what kind of "problems" you imagine might happen.
–
S.LottDec 15 '11 at 3:13

1

@S.Lott: You are mistaken. For non-REST static files that is not the norm. The content-type header is. Try it - your browser will ignore the url's extension and respect the header. That is the standard in HTTP.
–
qesDec 15 '11 at 3:42

@qes: Interestingly, my default Apache setup which serves static files from a directory tree uses the file name and extension in the same obvious way that the question does. The content type header -- on the response -- indicates the type of the response. It doesn't indicate the type being requested.
–
S.LottDec 15 '11 at 3:44

1

@S.Lott: I don't intend to be absolutist, and you can see in my answer I provided four different ways to specify the format. But the OP asked about REST. Using an extension, and even so much more so using something like /path/to/json/resource, is not REST. ?format=JSON, using the query string, was the fourth item in my answer. But using the path is practically an antithesis of REST. If REST isn't what you or the OP wants, call it a Web API or REST-like. REST means something fairly specific.
–
qesDec 15 '11 at 16:03

2 Answers
2

A resource may have more than one representation. There are four frequently used ways of delivering the correct resource representation
to consumers:

Server-driven negotiation. The service provider determines the right representation from prior knowledge of its clients or uses the
information provided in HTTP headers like Accept, Accept-Charset,
Accept-Encoding, Accept-Language, and User-Agent. The drawback of this
approach is that the server may not have the best knowledge about what
a client really wants.

Client-driven negotiation. A client initiates a request to a server. The server returns a list of available of representations. The
client then selects the representation it wants and sends a second
request to the server. The drawback is that a client needs to send two
requests.

Proxy-driven negotiation. A client initiates a request to a server through a proxy. The proxy passes the request to the server and
obtains a list of representations. The proxy selects one
representation according to preferences set by the client and returns
the representation back to the client.

URI-specified representation. A client specifies the representation it wants in the URI query string.

I would consider a URI based differentiation to be the least preferable method.

Aside of SEO or aesthetics implications there are no pros or cons I know of.

Perhaps it could affect some caching setups that could avoid caching URLs with query strings (in the case you would use a query string argument to specify the format), but this is not really an issue of your API.

Perhaps it could be said that using extensions is more "REST" as it represents the resource in a better way. Perhaps some libraries/frameworks have a preference for some or other scheme in order to expose or access resources.

I would suggest extensions are the least "REST" as it creates multiple URI's to the same resource, whereas REST would prescribe that each individual resource have only one unique URI - it would also prescribe using the facilities that already exist in HTTP - i.e., the appropriate headers.
–
qesDec 15 '11 at 2:50

I would think the extension is the most REST since the type is embedded in the URI.
–
S.LottDec 15 '11 at 3:14

1

@S.Lott: The "type" is simply a representation of a resource. Resources have global identifiers, not each representation of a resource. A core concept of REST is using the existing facilities of HTTP where appropriate, specifically including media type headers (en.wikipedia.org/wiki/Representational_state_transfer). What about links in the document? Using extensions implies that you will also be altering all the links in the resource with the extension. Using headers is much more appropriate.
–
qesDec 15 '11 at 3:39

Resources have global identifiers /path/to/resource. Followed by the type encoding after the resource ID, .html for example. That's seems to provide a way to transfer the representation of an object's state in a specific encoding. "altering all the links in the resource with the extension"? What does this mean?
–
S.LottDec 15 '11 at 3:43

a REST resource without hyperlinks isn't REST. So if I request a resource in json content, it should contain hyperlinks - e.g., a link to a related (sub) object (rather than containing the content of that resource - that is, a record of a person wouldn't embed the person's order info, it would contain links to the order resources themselves). Using headers, the link would always be canonical "myapi.com/MyPerson/Order/1&quot;, but when using extensions I'd have to spit it out as ".../Order/1.json" or ".../Order/1.xml" depending. The client should use the accepts header for this, not ext.
–
qesDec 15 '11 at 4:03