Designing Javascript APIs | Hacker News Reader

Designing Javascript APIs

blog.filepicker.io

71 pointsananddass10 comments

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.

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

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.

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.

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.

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.

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

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.

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

remove the comma from the sentence.

Good catch. Edited it. Thanks for the feedback

Reply on news.ycombinator.com