

How to Design a Good API & Why it Matters - helwr
http://www.infoq.com/presentations/effective-api-design

======
csytan
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

~~~
shafqat
Why no XML as response type?

~~~
mechanical_fish
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.

~~~
n8agrin
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.

------
patio11
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
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/>) 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.

~~~
patio11
_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
Have you looked at: <http://code.google.com/apis/ajax/playground/>

Visualization > Bar Chart

------
pierrefar
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.

------
vlad
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>

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

------
icefox
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>

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

~~~
Niten
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.

------
amalcon
Can we get a [video] marker?

