Hacker News Reader

Comment by csytan | Hacker News Reader

Although this talk is mostly slanted towards language APIs, I thought I'd share some tips for writing Web APIs:

  - Don't roll your own auth.  
    Use HTTPS and include username/password in POST parameters.
  - Avoid Sessions.
  - Strict REST is overrated:
    Browser support is universal for GET and POST, and patchy for everything else.
  - Make URLs easy to construct
  - Use GET requests to read data from your server.
    Use POST requests when changing data on your server.
  - Requests: URLencoded parameters
  - Response: URLencoded parameters, CSV, or JSON. Avoid XML.
  - Asynchronous responses:
    Let the user set a POST url to their web service in the request.
  - JSONP for browser based APIs

View on HN

  - Strict REST is overrated:
  Browser support is universal for GET and POST, and patchy
  for everything else.

Don't assume your resources will be consumed by browsers only. I still think it makes a good idea to have proper verbs and work around current browser limitations by passing hidden "method" field.

Yes, PUTs and DELETEs are nice but they are also sometimes blocked by proxies, on the assumption that browser don't do that, so they can't be needed.

Can you give an example of rolling your own auth the wrong way? Sometimes I get frustrated by the built-in auth in web frameworks, especially when designing single sign on, but I'm not sure which components are must-keeps, versus being replaceable.

Why no XML as response type?

One reason: JSON is more terse which reduces payload size.

Big response payload. Annoying to parse -- slow, or requires fiddly libraries with lots of features you aren't gonna use anyway, or both. Difficult to read. Also: Overkill.

One of my favorite lines was uttered by Philip Greenspun in 2000, back when XML was such a mindless fad that some companies were actually marketing themselves as "XML companies": "how come nobody ever talks about being a comma-separated-values company?" It was a good question then, and now that JSON and YAML are widely known and supported it is an even better question.

I could not agree more. I work daily with xml encoded apis and it's never a simple task to parse and normalize data. JSON on the other hand gives you normalized types out of the box. Very handy.

JSONP is great for browser-facing APIs, because it can be loaded from anywhere bypassing the browsers same origin policy. However, those policies are there for a reason. Only use JSONP for public data, never for any kind of secret or access-restricted data. Especially not if access is restricted bases on cookies or IP number. Session IDs that can used to access secret data are also secret.

For asynchronous, web hooks may not be the answer if clients can be behind a firewall. It's too much work to set up an externally accessible resource just for this. Polling or some sort of "job" resource works great too. When we designed the Windows Azure management API, we wound up offering both and it has worked out pretty well.

Reply on news.ycombinator.com