5 ms·
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 a
by csytan 17y ago
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
- rimantas 17y ago- 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.
- vorador 17y agoYes, 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.
- sriramk 17y agoFor 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.
- shafqat 17y agoWhy no XML as response type?
- sant0sk1 17y agoOne reason: JSON is more terse which reduces payload size.
- mechanical_fish 17y agoBig 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.
- n8agrin 17y agoI 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.
- euroclydon 17y agoCan 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.
- TorKlingberg 17y agoJSONP 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.