

Designing Javascript APIs - ananddass
http://blog.filepicker.io/post/34767202473/designing-javascript-apis

======
simonsarris
This is kinda thin, it reads more like an ad than anything else :/

I mean _of course_ you shouldn't make breaking changes to your API unless you
must. _Of course_ if its hard to use its not good enough. These are universal
truths that apply to most anything that other people build upon or merely use.

I've spent the last two years making a JavaScript API and I feel like there's
so much more real substance they could talk about here. Writing an API is a
very interesting process, and its _hard_ , harder than writing a general
program or even a language.

You don't just have to consider users needs or a grammar. Instead you have to
consider all the things your clients (other programmers) might want to do,
_and_ all of the things their users might want to do.

This means you have to be extremely forward thinking, considering all the ways
programmers might err while building with your library. When making general
programs you have to worry about shooting yourself in the foot. With an API,
you have to put forth _U.N. Peacekeeping_ levels of effort to make sure nobody
is going to shoot anybody or themselves. (Hopefully with better than U.N.
Peacekeeping levels of success!)

> If it’s hard to use, it’s not good enough (meaning you have to use it first)

This can't be stressed enough though. One of the lessons I learned here is
that making a large number of sample applications (I'm at 44 little apps and
counting for my lib) exposes a vast amount of untold hangups, issues, and
_wishes._ It's incredible the things you demand from your API once you start
using it compared to the things you thought you'd want. And they've exposed
far more kinks than testing alone could have shown me.

Ah I've rambled a bit. Maybe I should write my own experiences later tonight.

~~~
brettcvz
There's always a balance between giving an overview for people who have never
done this sort of thing before and writing to the aficionados with the battle
scars of having done this a few times. Happy to share more detailed notes
here, but as it was the original post was quite long already.

I would very much agree with you - the difficulty in writing APIs well come
from the fact that 1) it is challenging to predict how people will use it, so
you have to code defensively, make sure it's accessible to beginners and
sufficiently powerful for experts. 2) once you've published it, even small
tweaks become highly painful, increasingly so as you see success.

Love the parallels with U.N. Peacekeeping

------
EzGraphs
Nice systematic approach:

 _Draw a grid, with the models/nouns/objects on the one axis and the
verbs/actions on the other. Fill in a square if you can perform the given
action on the given object...If you can fill in every square, consider that a
complete “block”, a good candidate for an API design._

~~~
ananddass
Thanks! There are a couple of more techniques we used. Will follow up with a
separate post sometime later this month. Also would be interesting to see what
approaches simonsarris uses.

------
d0m
Thanks for sharing. Something you touched on but didn't explicitly stated is
to have a standard and uniform interface everywhere.

My go-to example would be JQuery.. It feels like once you understand
$('a.test').click(function() {..});, you understand and, most importantly,
_feel_ how everything else behave.

For instance, what if I don't want a click but a mouse hover? I don't have to
read the doc or google.. I can just try .hover() and 9 times out of 10 it will
work.

A bad API forces you to spend hours reading the doc because the 10 most
obvious tries failed. Most of the time, these ugly APIs come also with bad or
lack of documentation and backward-breaking changes without notifications.
Yes, I'm talking about Facebook' API.

~~~
zaptheimpaler
Agreed, its a pleasure working with jQuery because 1. things are consistent &
complete , so its very easy to guess what a function should be named and how
it would work, and 2. the docs are great. every function has an easy small
description and some good examples.

2\. also reflects how well chaining works.

------
potkor
> Developers should never have to use a try-catch.

Is the "no exceptions" rule common in Javascript? Are exceptions trouble in JS
for some technical reason compared to eg Python?

~~~
ville
Since continuation-passing style is so popular in asynchronous code, errors
are typically passed to the callback instead of throwing them. If an error was
thrown in, say, a callback for an XMLHttpRequest the original caller would not
catch it.

------
c4n4rd
> Never, make breaking changes to your API. Unless you must.

remove the comma from the sentence.

~~~
ananddass
Good catch. Edited it. Thanks for the feedback

