4 ms·

I like the trick of placing something meaningful at the api root url, will use that in the future. "You of course need a JSON viewer plugin to do this." Why

I like the trick of placing something meaningful at the api root url, will use that in the future. "You of course need a JSON viewer plugin to do this." Why not emit your JSON slightly prettier from the server side? http://stackoverflow.com/questions/86653/how-can-i-pretty-format-my-json-output-in-ruby-on-rails http://stackoverflow.com/questions/86653/how-can-i-pretty-fo...

cicloid 15y ago
Maybe because of the overhead on rendering time and extra bytes. On a couple thousand requests the latency is not so noticeable. But on the long run maybe the API user should have a plugin on the client side to do that kind of beautification.
- rglullis 15y ago
  Not necessarily. You would only render the prettified version when the client has an Accept header that shows more capabilities than application/json. Which, by the way leads to my single complaint with this API: it only renders JSON. To call it truly "self-documenting", I should just browse to http://www.heyzap.com/api/v1/ http://www.heyzap.com/api/v1/ (ok, second complaint: the "v1" also belongs in a header, not the URI) and get an HTML page describing the resource, and links to the other endpoints. Bonus points if this HTML allows me to run the queries with overridden parameters.
  - cicloid 15y ago
    You have a point with the rendering option from the accept header... About the v1 versioning in the URL, I understand your suggestion. But I see that little characteristic as a "no developer left behind" program for developers with less experience. Also the format as an extension for your resource serves the same purpose
immad 15y ago
Hadn't thought of that. Done. I may revise if it increases server load significantly but it looks good for now: http://www.heyzap.com/api/v1/activity/android http://www.heyzap.com/api/v1/activity/android
- cellularmitosis 15y ago
  Perhaps this would be a good place to tie into the "Accept:" request header? If it says text/html in Accept:, you're still going to return JSON, but you can use this as a hint that it is probably being read by a human, and you can pretty print it. But if you see application/json in Accept:, then you assume it's an API call from a phone or script and you minify it instead. Edit: however, that requires cooperation from others, so is prone to failure. Perhaps also take hints from the user agent string? Edit 2: drat, someone already beat me to this suggestion. However, I'll use this as an excuse to pimp my last weekend hack: adding an Accept: decorator to itty.py http://news.ycombinator.com/item?id=3665743 http://news.ycombinator.com/item?id=3665743

cicloid 15y ago

Maybe because of the overhead on rendering time and extra bytes. On a couple thousand requests the latency is not so noticeable. But on the long run maybe the API user should have a plugin on the client side to do that kind of beautification.

rglullis 15y ago
Not necessarily. You would only render the prettified version when the client has an Accept header that shows more capabilities than application/json. Which, by the way leads to my single complaint with this API: it only renders JSON. To call it truly "self-documenting", I should just browse to http://www.heyzap.com/api/v1/ http://www.heyzap.com/api/v1/ (ok, second complaint: the "v1" also belongs in a header, not the URI) and get an HTML page describing the resource, and links to the other endpoints. Bonus points if this HTML allows me to run the queries with overridden parameters.
- cicloid 15y ago
  You have a point with the rendering option from the accept header... About the v1 versioning in the URL, I understand your suggestion. But I see that little characteristic as a "no developer left behind" program for developers with less experience. Also the format as an extension for your resource serves the same purpose

immad 15y ago

Hadn't thought of that. Done. I may revise if it increases server load significantly but it looks good for now: http://www.heyzap.com/api/v1/activity/android http://www.heyzap.com/api/v1/activity/android

cellularmitosis 15y ago
Perhaps this would be a good place to tie into the "Accept:" request header? If it says text/html in Accept:, you're still going to return JSON, but you can use this as a hint that it is probably being read by a human, and you can pretty print it. But if you see application/json in Accept:, then you assume it's an API call from a phone or script and you minify it instead. Edit: however, that requires cooperation from others, so is prone to failure. Perhaps also take hints from the user agent string? Edit 2: drat, someone already beat me to this suggestion. However, I'll use this as an excuse to pimp my last weekend hack: adding an Accept: decorator to itty.py http://news.ycombinator.com/item?id=3665743 http://news.ycombinator.com/item?id=3665743