Fear of not being “RESTful”

Fear of not being ”RESTful” affects web developers, and they do unnatural things with their web applications. Say, some developers think that absence of query string makes their URLs “RESTful” and “clean”:

/search/my search query/
/qa/participated/page/4/

There is nothing “unRESTful” in query strings. When we’re searching, we’re actually requesting data from /search/ resource. There is no /search/my search query/ resource, it’s always /search/. This resource accepts field with name and value (just like function accepts argument that has name and value, too) that is text we are searching for: /search/?q=my+search+query.

Same with pagination: there is /qa/participated/ resource which contains results, and we consume results page by page. There is no /qa/participated/page/ resource, as there is no /qa/participated/page/N/ resource.

Some developers think that “response in format of your choice” is what “RESTful” is about. Let me tell you why /qa/?format=json is not “RESTful”.

Part of API construction is careful selection of response format. For instance, if it’s profiles API, it may be XML or XHTML: it is much easier to use hCard µf with them. If it is a list of blog posts or questions (yes, abusing QA again :) it may be Atom feed. If it is a list of Tweets, it may be Activity Stream (Atom or JSON).

Some developers are confused about purpose of Accept HTTP header: they think it is a good way to tell API in which format they want to get data. They are right, Accept header defines a range of types client can accept, but, as I said in previous paragraph, such behaviour is not applicable to APIs: API designer must choose some specific format for data, and API must respond with “406 Not Acceptable” if content is not acceptable according to request.

Sometimes developers add format-specific extensions to URLs: /qa/123.json. This is bad too, as client code does not (I hope) really care about that extension. Plus, format is already defined in documentation of API.