Question

We have an ecommerce website that displays groups of products by category using a URL format that maps almost exactly to the REST URL format we would like to use for our forthcoming API.

e.g. example.com/products/latest or example.com/products/hats

Is it a valid pattern to use the same URL for visible (HTML) and invisible (JSON) results, and to use the Accept http request header to determine what should be returned.

i.e. if you call example.com/products/latest with Accept: application/json you get just the product data, but if you use text/html you get the full HTML page (header, footer, site chrome etc.)

And if so, is this a good idea – will we run into problems if, for instance, the website needs to change, but the API needs to be stable?

UPDATE: some helpful resources – here is an article[1] by Peter Williams discussing the use of the HTTP Accept header to version APIs, and I have also referenced an SO question[2] that reveals some of the problems of using this approach. Probably better to use a custom HTTP header?

[1] Making the case for using Accept: http://barelyenough.org/blog/2008/05/versioning-rest-web-services/
[2] Problems with jQuery (& IE): Cannot properly set the Accept HTTP header with jQuery
[3] Making the case for using Accept: http://blog.steveklabnik.com/2011/07/03/nobody-understands-rest-or-http.html
[4] Sitting on the fence: http://www.informit.com/articles/article.aspx?p=1566460

Answer 1

Using http headers is generally becoming the accepted way of determining this.

In ASP.NET MVC for example there is an IsAjaxRequest method that checks for the X-Requested-With header and if it is equal to "XMLHttpRequest" it is deemed to be an ajax request.