Building Non-shit APIs with JavaScript

Your JS LibraryDan 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

RTFMTuesday, May 3, 2011

Short attention spanTuesday, May 3, 2011

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? ]) ]) ]);

function elementBuilder(name) { return function(attributes, children) { return html.element(name, attributes, children); }}

function generateBuilderFunctions(elements) { for (var i=0, len=elements.length; i < len; i++) { html[elements[i]] = createElementBuilder(elements[i]); }}

generateBuilderFunctions("p|div|span|strong|em|img|table|tr|td|th|thead|tbody|tfoot|pre|code|h1|h2|h3|h4|h5|h6|ul|ol|li|form|input|textarea|legend|fieldset|select|option|blockquote|cite|br|hr|dd|dl|dt|address|a|button|abbr|acronym|script|link|style|bdo|ins|del|object|param|col|colgroup|optgroup|caption|label|dfn|kbd|samp|var".split("|"));

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);

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

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

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) { rpc(con).call('getData', function(result) { alert(result); });});

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

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

Back to the DOM Builder

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? ]) ]) ]);

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'}) ));

function elementBuilder(name) { 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]); } }

return html.element(name, attributes, children); }}

Flexibility

Remember: you can't please everyone

Don’t try to second guess every use case

Options hashes != flexibility

28 options!Tuesday, May 3, 2011

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

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

..duck typing

Meanwhile, back in DOM Builder land...

function elementBuilder(name) { 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); }

return html.element(name, attributes, children); }}

var timeline = // an array of Tweet objects

document.appendChild(html.div({ id: 'timeline' }, timeline));

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

@jointheflocktwitter.com/jobsdan@twitter.com

Eye of the BeholderTuesday, May 3, 2011

ChainingTuesday, May 3, 2011

Building Non-shit APIs with JavaScript

Technology

Transcript of Building Non-shit APIs with JavaScript

Hypermedia APIs mit Javascript und Python

Shit Sheet

HTML5 JavaScript APIs

Exploring Google APIs with Python & JavaScript

Tying Shit

Scrib Shit

Human APIs - expanding the mobile web or are robots coming to JavaScript?

Information-ﬂow security for JavaScript and its APIsandrei/jcs-jsflow.pdf · Information-ﬂow security for JavaScript and its APIs ... This paper presents a dynamic mechanism for

Build Win10 UWP Game With Cocos & Unitydownload.microsoft.com/download/8/B/F/8BFE821E-EAE9-409A-859D-B4F3EDED... · Cocos2d-x Games JavaScript APIs Lua APIs C++ APIs JS binding JS

JavaScript APIs - The Web is the Platform - MDN Hack Day, Montevideo

Avatar shit

safe JavaScript APIs - owasp

Getting Started with the ArcGIS API for JavaScript€¦ · ArcGIS JavaScript APIs – Why JavaScript? It’s your future ;-) • Lightweight web GIS • Pervasive • Cross-platform,

HTML5 JavaScript APIs - remy sharp's b:log

JavaScript APIs you’ve never heard of (and some you have)

JavaScript APIs · APIs •Canvas •Drag & Drop •History •Inline Editing •Messaging •Of!ine Apps •Video & Audio •Geolocation •Local Storage •Selectors •Server Events

JavaScript APIs - The Web is the Platform

Tough Shit. Tough Shit - · PDF fileThats Tough Shit. Tough Shit isnt a cripple and isnt blind. ... Tough Shit, helpless and awkward, goes entirely his own way, so clumsily its to

Building Hypermedia APIs in JavaScript

JavaScript APIs and Libraries