5 ms·

Show HN: Web analytics with API only approach

33 points by petrohi 15y ago

pwim 15y ago
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.
- petrohi 15y ago
  > 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.
  - nbpoole 15y ago
    Content-type for JSON is application/json For JSONP, you might consider application/javascript (http://stackoverflow.com/questions/111302/best-content-type-to-serve-jsonp http://stackoverflow.com/questions/111302/best-content-type-...)
- nl 15y ago
  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. 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 http://wiki.apache.org/solr/CoreQueryParameters#wt
  - bluesmoon 15y ago
    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.
    - petrohi 15y ago
      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.
- petrohi 15y ago
  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.
  - jmathai 15y ago
    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.
  - stock_toaster 15y ago
    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?

33 points by petrohi 15y ago

pwim 15y ago

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.

petrohi 15y ago
> 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.
- nbpoole 15y ago
  Content-type for JSON is application/json For JSONP, you might consider application/javascript (http://stackoverflow.com/questions/111302/best-content-type-to-serve-jsonp http://stackoverflow.com/questions/111302/best-content-type-...)
nl 15y ago
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. 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 http://wiki.apache.org/solr/CoreQueryParameters#wt
- bluesmoon 15y ago
  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.
  - petrohi 15y ago
    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.
petrohi 15y ago
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.
- jmathai 15y ago
  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.
- stock_toaster 15y ago
  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?