It seems that newer websites (and API's especially) make use of request formats by adding the expected format to the end of the URL path.


Are their any problems with this approach? Are there any studies or outlines of the pros and cons of doing this instead of just listing the resource without a file type extension?

  • 1
    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, 2011 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.Lott
    Dec 15, 2011 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. Dec 15, 2011 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.Lott
    Dec 15, 2011 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. Dec 15, 2011 at 16:03

2 Answers 2


From xml.com:

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

  1. 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.
  2. 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.
  3. 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.
  4. 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 wrote an article about the aspect of a few public REST APIs... perhaps it can help you: a look into varios REST APIs.

  • 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. Dec 15, 2011 at 2:50
  • I would think the extension is the most REST since the type is embedded in the URI.
    – S.Lott
    Dec 15, 2011 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. Dec 15, 2011 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.Lott
    Dec 15, 2011 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", 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. Dec 15, 2011 at 4:03

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.