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
- 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.
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.
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.
Does anyone here use Google APIs? Care to comment on your experiences? My experience with them has... not wowed me as much as their customer-facing or advertising products.
In terms of great API design for startups -- meaning both "something to emulate" and "something to convince other startups to use me" I think MailChimp and Twilio are both top notch. Their documentation is excellent, they make doing easy things really easy, and you'll quickly get actual business value out of them. By comparison, many of the Google APIs I've seen have documentation which scares the Big Freaking Java Enterprise Developer in me, no useful defaults, huge commitments required for integration, and many hours of work required before I see anything useful.
See, for example, the Google chart API. You would think doing a sales barchart should be pretty easy, right? That is pretty much the Hello World I'm A Barchart, right? Even using a wrapper in my language of choice, that was nearly half a day of banging my head against the wall. I had my entire Mailchimp integration done in less time.
Maybe the difficulty you found with their chart tools reflects some inherent complexity of the problem? Did you ever find an easier / more useful library?
In the absence of a better solution, I would wager that it's just a hard problem that they're trying to solve.
Did you ever find an easier / more useful library?
In the full knowledge that this comparison is apples versus porcupines: OpenFlashChart 2 is my favorite charting software ever. It gives you quite a bit of fine-grained control, but if your needs are I Want A Freaking Bar Chart then in ten minutes you will have A Freaking Bar Chart. There are no steps such as "OK, first things first: we're going to need you to scale your data down to fit in the range 0 to 100. Then you pass that to us with your min and maxes -- you have to specify those, we don't pick sanely -- and we'll recreate your original data for you."
I'm sure there is a good technical reason for that but, ahem, I use APIs so that I don't have to care about good technical reasons for things being hard. That is the sort of ugly implementation detail that the API is supposed to bury for me. (Google Charts is still impressive, by the way, in that it totally abstracts away server administration and scaling issues from graphical processing, which if you were to scratch build yourself would not be pleasant. Also, since you end up with standard image tags, you can use it with any browser, down to and including the ancient Japanese cellphone I often check my stats from. That said: it could be better. I see they have a Javascript version now and it looks much, much saner.)
I also used the search API here: http://chir.ag/wiki/bingo - Wikipedia search. I almost always end up doing site:wikipedia.org when I'm looking for articles on a topic. Now I just go to chir.ag/wiki/%s and it works great. I do not have to do anything on the server end and Google's JS search APIs handle everything. It works especially well when I don't know the correct spelling or even the most relevant keywords.
I wouldn't think of Google API as being complex enterprise-y APIs. They have really powerful JS APIs that you can use on the client side. This puts less stress on the server and you don't get rate limited. I've also used YouTube API in the past and it was pretty decent.
While building web apps, one thing I preach (and mostly stick to) is: build the API first and use it to build your app. This API could be simply the core code for it (say a set of functions), with error checking and everything, that you use to build your app.
Later, you wrapit in a thin I/O layer for use over HTTP for external use.
This is offtopic, but I'm really impressed with whoever designed InfoQ's interface for watching presentations and interviews. Being able to watch the slides and the presenter simultaneously in separate panes is an approach I wish more sites would copy.
I also recall a recent interview I watched on their site: there was a list of topic summaries below the video, and you could click on any of the topics in the list to skip right to that point in the video. It's a very functional user interface as these things go.
That's too bad, I hadn't tried that. Though offhand I can't think of a good way to even try scaling these presentation slides to an iPhone-sized screen.
