How to Design a Good API & Why it Matters
infoq.com
infoq.com
- 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.
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.
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.
In particular google-collections (http://code.google.com/p/google-collections/) and guice (http://code.google.com/p/google-guice/) are, in my qualitative estimation, fabulously designed.
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.
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.)
Visualization > Bar Chart
Very easy to set up, and attractive too. The free library has a stack of different types.
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.
Later, you wrapit in a thin I/O layer for use over HTTP for external use.
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.