Building Non-shit APIs with JavaScript

Your JS Library
Dan Webb AKA @danwrong

Tuesday, May 3, 2011

In the beginning...


$("p.surprise").addClass("ohmy").show("slow");


We all know what
happened next...
jQuery

The Rest


Internals were not
important...


...what had John created
was a great interface


"All programmers are
API designers"
Joshua Bloch (http://lcsd05.cs.tamu.edu/slides/keynote.pdf)


The API is priority #1


❖ Predictability
❖ Simplicity
❖ Flexibility


Predictability


RTFM

Short attention span

Think about your
audience...


...use conventions people
already know


Language conventions
and standard library


THIS IS JAVASCRIPT


useCamelCase, yesReally.


Be careful with polyfills


Popular JS libraries


var paper = Raphael(10, 50, 320, 200);

var c = paper.circle(50, 40, 10);

c.attr("fill", "#f00");

c.show();


The problem domain


a.internal {
color: #44e534;
text-decoration: none;
}

$('a.external').css({
color: '#44e534',
textDecoration: 'none'
});


Example: creating a
DOM Builder


node.innerHTML = '<form method="post" action="/action">' +
'<p>' +
'<label>' +
'Username: <input type="text" name="username">' +
'</label>' +
'<label>' +
'Password: <input type="password" name="password">' +
'</label>' +
'</p>' +
'</form>';

var form = document.createElement('form');
var p = document.createElement('p');
form.setAttribute('action', '/login');
form.setAttribute('method', 'post');
var usernameLabel = document.createElement('label');
var usernameText = document.createTextElement('Username: ');
var usernameInput = document.createElement('input');
usernameInput.setAttribute('type', 'text');
usernameInput.setAttribute('name', 'username');
form.appendChild(p);
p.appendChild(usernameLabel);
// ... at this point I decided to give
// all this up and become a farmer


var form = html.element(
'form',
{ action: '/login', method: 'post' }
[
html.element('p', {}, [
html.element('label', {}, [
document.createTextElement('Username: '),
html.element('input', { type: 'text', name: 'username' }, []),
// ... you get the idea
])
])
]
);


var form = html.form({ action: '/login', method: 'post' },
[
html.p({}, [
html.label({}, [
document.createTextElement('Username: '),
html.input({ type: 'text', name: 'username' }, []),
// ... you still get the idea, right?
])
])
]
);


Simplicity


Don’t make me
RTFM again...


Sensible defaults


var evt = document.createEvent("MouseEvents");

evt.initMouseEvent("click", true, true, window,
0, 0, 0, 0, 0, false, false,
false, false, 0, null);


element.addEventListener('input', function() {
// do some front-end magic
}, false);


Use options hashes for
optional arguments


evt.initMouseEvent("click", {
bubble: false,
relatedTarget: thing
});


http://blog.rebeccamurphey.com/objects-as-
arguments-in-javascript-where-do-y


Function calls
should read well


// replace oldNode with newNode - DOM API
oldNode.parentNode.replaceChild(newNode, oldNode);

// Dojo
dojo.place(newNode, oldNode, "replace");

// jQuery
$(oldNode).replaceWith(newNode);


Mask complexity if
possible


var con = xd.connect({ src: 'http://danwebb.net/receiver' });

con.bind('ready', function() {
rpc(con).call('getData', function(result) {
alert(result);
});
});


xd.connect({ src: 'http://danwebb.net/receiver' }, function(con) {
alert(result);
});
});


var con = xd.connect({ src: 'http://danwebb.net/receiver' });

alert(result);
});


Back to the DOM Builder


var form = html.form({ method: 'post', action: '/login' },
html.p(
html.label(
'Username: ',
html.input({ type: 'text', name: 'username' })
),
html.label(
'Password: ',
html.input({ type: 'password', name: 'pass' })
),
html.input({ type: 'submit', value: 'Login'})
)
);


return function() {
var attributes = {}, children = [],
args = Array.prototype.slice.call(arguments);

// if the first arg is not a element or a string then its an attributes hash
if (!args[0].nodeType && typeof args[0] != 'string') {
attributes = args.unshift();
}

// children can be an array or remaining args
if (Array.isArray(args[0])) {
args = args[0];
}

// add rest of args as children converting any strings to text nodes
for (var i=0, len=args.length; i < len; i++) {
if (typeof args[i] == 'string') {
children.push(document.createTextNode(args[i]));
} else {
children.push(args[i]);
}
}

}
}


Flexibility


Remember: you can't
please everyone


Don’t try to second
guess every use case


Options hashes != flexibility


28 options!

Add hackability


public, internal, protected


var lib = (function() {
var private = function() {
// you can't mess with me
};

return {
_internal: function() {
// you probably shouldn't mess with me
},
public: function() {
// I'm part of the API - call me sometime
}
}
}());


...using functions


// https://github.com/ender-js/Ender

$._select = function(selector, root) {
return Sizzle(selector, root);
}

$._select = function (selector, root) {
return (root || document).querySelectorAll(selector);
});


..inheritance


// github.com/danwrong/loadrunner

function Mustache(path) {
this.path = path;
}
Mustache.prototype = new loadrunner.Dependency;
Mustache.prototype.start = function() {
var me = this;

$.get(this.path, function(result) {
var template = Mustache.parse(result);
me.complete(template);
});
}

using(new Mustache('thing.mustache'), function(template) {
template.evaluate({ a: 'yep', b: 'nope' });
});


..duck typing


Meanwhile, back in
DOM Builder land...


return function() {
// code collapsed for clarity

// add rest of args as children
// converting any strings to text nodes
for (var i=0, len=args.length; i < len; i++) {
if (typeof args[i] == 'string') {
node = document.createTextNode(args[i]);
} else {
if (typeof args[i].toDOM == 'function') {
node = args[i].toDOM();
} else {
node = args[i];
}
}

children.push(node);
}

}
}


Create a framework for
solving your problem...


...then build your library
on top of that


You got yourself a
plugin system


Build tools to solve the
problem


❖ Design up front
❖ Make use of conventions
❖ Don’t make me think
❖ Build in hackability


Questions?
@danwrong


@jointheflock
twitter.com/jobs
dan@twitter.com


Eye of the Beholder

Building Non-shit APIs with JavaScript

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (20)

Similar to Building Non-shit APIs with JavaScript

Similar to Building Non-shit APIs with JavaScript (20)

More from danwrong

More from danwrong (8)

Recently uploaded

Recently uploaded (20)

Building Non-shit APIs with JavaScript