9 ms·

How to Design a Good API & Why it Matters

70 points by helwr 17y ago

patio11 17y ago
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.
- dschobel 17y ago
  My only experience has been with the java frameworks coming out of Google and those are top-notch. In particular google-collections (http://code.google.com/p/google-collections/ http://code.google.com/p/google-collections/) and guice (http://code.google.com/p/google-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.
  - patio11 17y ago
    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.)
    - chime 17y ago
      Have you looked at: http://code.google.com/apis/ajax/playground/ http://code.google.com/apis/ajax/playground/ Visualization > Bar Chart
    - benologist 17y ago
      There's an amazing set of charts available here too: http://www.fusioncharts.com/free/ http://www.fusioncharts.com/free/ Very easy to set up, and attractive too. The free library has a stack of different types.
- chime 17y ago
  I've used Google APIs in many projects and love them. Here's one: http://chir.ag/projects/drop-search/ http://chir.ag/projects/drop-search/ I also used the search API here: http://chir.ag/wiki/bingo 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.
spitfire 17y ago
For a website with such a heavy "enterprise" slant it sure is very slow to load.
vlad 17y ago
Good find. The author has since updated the article, below. It's also a written article instead of a flash presentation. http://news.ycombinator.com/item?id=1190419 http://news.ycombinator.com/item?id=1190419
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 ago
    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.
- sriramk 17y ago
  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.
- shafqat 17y ago
  Why no XML as response type?
  - sant0sk1 17y ago
pierrefar 17y ago
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.
amalcon 17y ago
Can we get a [video] marker?
icefox 17y ago
I highly recommend checking out the Little Manual of API Design for anyone looking for more on this topic: http://chaos.troll.no/~shausman/api-design/api-design.pdf http://chaos.troll.no/~shausman/api-design/api-design.pdf
Niten 17y ago
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.
- defied 17y ago
  Too bad you can't read the content on a mobile device (iPhone)
  - Niten 17y ago
    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.

70 points by helwr 17y ago

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.

dschobel 17y ago
My only experience has been with the java frameworks coming out of Google and those are top-notch. In particular google-collections (http://code.google.com/p/google-collections/ http://code.google.com/p/google-collections/) and guice (http://code.google.com/p/google-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.
- patio11 17y ago
  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.)
  - chime 17y ago
    Have you looked at: http://code.google.com/apis/ajax/playground/ http://code.google.com/apis/ajax/playground/ Visualization > Bar Chart
  - benologist 17y ago
    There's an amazing set of charts available here too: http://www.fusioncharts.com/free/ http://www.fusioncharts.com/free/ Very easy to set up, and attractive too. The free library has a stack of different types.
chime 17y ago
I've used Google APIs in many projects and love them. Here's one: http://chir.ag/projects/drop-search/ http://chir.ag/projects/drop-search/ I also used the search API here: http://chir.ag/wiki/bingo 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.

spitfire 17y ago

For a website with such a heavy "enterprise" slant it sure is very slow to load.

vlad 17y ago

Good find. The author has since updated the article, below. It's also a written article instead of a flash presentation. http://news.ycombinator.com/item?id=1190419 http://news.ycombinator.com/item?id=1190419

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 ago
  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.
sriramk 17y ago
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.
shafqat 17y ago
Why no XML as response type?
- sant0sk1 17y ago

pierrefar 17y ago

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.

amalcon 17y ago

Can we get a [video] marker?

icefox 17y ago

I highly recommend checking out the Little Manual of API Design for anyone looking for more on this topic: http://chaos.troll.no/~shausman/api-design/api-design.pdf http://chaos.troll.no/~shausman/api-design/api-design.pdf

Niten 17y ago

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.

defied 17y ago
Too bad you can't read the content on a mobile device (iPhone)
- Niten 17y ago
  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.