Item — HN Reader

Your API is pretty strange. Some initial things that pop out on me:

json=true to specify the content type. Ideally, this should be from the accept header, but at the very least it should be possible to only specify one content type. Right now, I can specify json=true&xml=true.

Only using GET.

Session management on the client. Why would I want to log someone out?

Not using meaningful keys. s and t? Why not status and token?

HTTP codes should be used instead of status codes.

3 comments

> Your API is pretty strange. Some initial things that pop out on me: > json=true to specify the content type. Ideally, this should be from the accept header, but at the very least it should be possible to only specify one content type. Right now, I can specify json=true&xml=true.

I agree, content type selection currently is very rudimentary and ability to combine parameters could be confusing. We want to distinguish between JSON, JSONP, XML and CSV. We could use text/plain MIME type for CSV, text/xml for XML, but are there standard MIME types for JSON and JSONP?

> Only using GET.

API is currently immutable towards analytics data, so only GET is used.

> Session management on the client. Why would I want to log someone out?

It's less of the session management and more security token management. Log out is to revoke specified security token. We should be more explicit about this.

Content-type for JSON is application/json

For JSONP, you might consider application/javascript (http://stackoverflow.com/questions/111302/best-content-type-...)

Specifying content type as a parameter this makes debugging so much easier that I think it is worth it.

I agree with your other points. Specifically, the output type should be done the same way Solr does it: http://wiki.apache.org/solr/CoreQueryParameters#wt

I think he meant that it should have been type=json or type=xml instead of json=true/xml=true. The former has been pretty standard practice with REST APIs as far back as I can remember (2005 at least), as an alternative when Accept headers weren't possible.

Yes, type=json|jsonp|xml|csv would work. We would just need an extra parameter for JSONP to specify the name of the callback function.

Consideration for not using HTTP status codes was that they are not working very well with JSONP-type integration. This is when page JavaScript adds "call" script object to DOM and then expects call back when it's loaded. To pass error information in this case we need HTTP server to return 200.

If you are using jsonp (?callback=foo) then return a 200 and embed the response code in the response.

  foo({"err":{"code":500,"msg":"oh no. i broke!"},"response":null})

  foo({"err":null,"response":"hooray"})

If not using jsonp, then use the status codes IETF gave you. ;)

Most frameworks (WSGI, Rack) allow you to wrap the response and check for presence of the callback, and transform into a friendlier jsonp format. Then you can simply ignore it and code as normal. In this case, doesn't express (seems to be what you are using?) support route middleware too?

I agree here. Inspecting the response data is often easier and rarely harder than the HTTP code.

Just because REST says you should do it one way doesn't mean you should.