As developers, we know what good and bad JavaScript APIs "feel" like, and yet we struggle with designing the kind of APIs that we enjoy using. But principles of good JavaScript API design do exist, and it's possible to extract them from several key libraries in the the proliferating JavaScript landscape. In this session, Brandon Satrom will do exactly that, digging into the design aspects of popular libraries like jQuery, Backbone, Knockout, Modernizer, Kendo UI and others to enumerate the designed-in qualities of these libraries that make them not only popular, but a pleasure to use.

1. Secrets of Awesome JavaScript
API Design
Brandon Satrom
@BrandonSatrom
brandon@KendoUI.com

2. Read it @
bit.ly/
ZS5VYv

3. 3Big Ideas

4. Three ideas...

5. Three ideas...
1.APIs are “Developer UX”

6. Three ideas...
1.APIs are “Developer UX”
2.API Design is a universal practice

7. Three ideas...
1.APIs are “Developer UX”
2.API Design is a universal practice
3.API Design is a “principle-driven” art form

8. What is design?

9. What is design?
“form[ing] a plan or scheme of [some
thing]… for later execution”
- Oxford English Dictionary

10. Design is universal

11. We judge designs to be...
...elegant
...beautiful
...utilitarian
...simple
...or not...
Images from: http://www.greatbuildings.com/ and http://list25.com/25-ugliest-buildings-in-the-world/

12. We judge designs to be...
...elegant
...beautiful
...utilitarian
...simple
...or not...
Images from: http://www.greatbuildings.com/ and http://list25.com/25-ugliest-buildings-in-the-world/

13. We judge designs to be...
...elegant
...beautiful
...utilitarian
...simple
...or not...
Images from: http://www.greatbuildings.com/ and http://list25.com/25-ugliest-buildings-in-the-world/

14. We judge designs to be...
...elegant
...beautiful
...utilitarian
...simple
...or not...
Images from: http://www.greatbuildings.com/ and http://list25.com/25-ugliest-buildings-in-the-world/

15. “Mediocre design provably wastes
the world’s resources, corrupts the
environment, affects international
competitiveness. Design is
important, teaching design is
important.”
- Fred Brooks
Image of Fred Brooks from: http://en.wikipedia.org/wiki/File:Fred_Brooks.jpg
Poor Design is Costly

16. We apply design practices
to User Interfaces...
Images from: http://pinterest.com/fromupnorth/gui/

17. We call this practice,
User Experience (UX)
design...
Images from: http://pinterest.com/fromupnorth/gui/

18. What about API Design?

19. API Design is “Developer UX”

20. API Design is not JUST For
Library Authors...

21. ...modular JS is written to be
consumed...

22. ...the number of
consumers is
irrelevant.
Images from flickr.com/photos/powi/

23. In JavaScript, API design is
critically important...

24. Dynamic Language...

25. Anonymity of
consumers...
http://i.qkme.me/3qesq1.jpg

26. Ambiguity of Requirements...

27. Your users are smart...

28. Yeah, but my
users won’t...
Image from: http://idratherbewriting.com/wp-content/uploads/2012/08/rtfmtractor.jpg

29. Yeah, but my
users won’t...
Image from: http://idratherbewriting.com/wp-content/uploads/2012/08/rtfmtractor.jpg

30. A Tale of Ice &
Water

31. A Tale of Ice &
Water

32. A Tale of Ice &
Water

33. A Tale of Ice &
Water

34. A Tale of Ice &
Water

35. In Industrial
Design, this is
NOT an
acceptable
answer...
Image from: http://idratherbewriting.com/wp-content/uploads/2012/08/rtfmtractor.jpg

36. ... how is Software Different?
Image from: http://www.globalnerdy.com/wordpress/wp-content/uploads/2010/05/makeabetterfm.jpg

37. ... how is Software Different?
Image from: http://www.globalnerdy.com/wordpress/wp-content/uploads/2010/05/makeabetterfm.jpg
It’s Not.

39. Your users are smart...

40. http://thebus.net/sites/default/files/americas-next-top-hipster.jpg

41. ...but they are NOT...
you.
http://thebus.net/sites/default/files/americas-next-top-hipster.jpg

42. Design the “pit of success”
Image from: http://darrell.mozingo.net/2011/06/26/the-pit-of-success/

43. Example:
$("article.blogPost").fadeIn();
Use jQuery to select all article tags with the class “blogPost”

44. Example:
$("article.blogPost").fadeIn();
Use jQuery to select all article tags with the class “blogPost”
article.blogPost
{
border-­‐radius:
10px;
background-­‐color:
salmon;
box-­‐shadow:
0px
0px
10px
2px
#ccc;
}

45. Goals of API Design
Be Self-Describing
Prevent Errors
Make Users Fast
Image from: http://elliottbrown.files.wordpress.com/2012/04/sandcastles.png

47. Goals are not enough...

49. ...we need guiding principles...

50. Principles, not Rules

51. Principles, not Rules
Rules are rote, often applied without context
Principles encourage application of context

52. Principles Found in Physical Media
Images from: http://char.txa.cornell.edu/language/principl/principl.htm & http://www.greatbuildings.com/

53. Principles on display in popular
libraries...
Backbone
jQuery
Kendo UI
Modernizr
Moment.js
Underscore

54. The Four Principles
Unity & Harmony
Balance
Proportion
Emphasis

55. WARNING! This is ART, not
SCIENCE

56. Unity and Harmony
Image “Portrait of the children of Charles I” by Anthony Van Dyck from: http://char.txa.cornell.edu/language/principl/principl.htm

57. Unity and
Harmony (art)
Unity: The concept behind a work, or how the composer brings
everything together into a coherent whole.
Harmony: The placement of similar elements throughout a work,
yielding an uncomplicated and simple feel.
Painting by Robert Delauny, from: http://char.txa.cornell.edu/language/principl/principl.htm

58. Unity & Harmony (API Design):
Familiarity & Comfort
Extended Object creation in
Backbone
Widget Instantiation in
Kendo UI
Use similar and/or
unifying elements
through your library
to create familiarity
and comfort

59. Example:
Create Kendo UI Widgets from jQuery-selected DOM Elements
$("ul.tree").kendoTreeView();
$("ul.panel").kendoPanelBar();
$("div").kendoGrid();

60. Example:
Create Kendo UI Widgets from jQuery-selected DOM Elements
Each Widget is prefixed
with “kendo” and named in
a consistent, camel-cased
style
$("ul.tree").kendoTreeView();
$("ul.panel").kendoPanelBar();
$("div").kendoGrid();

61. Example:
Create Extended Objects with Backbone
var
Book
=
Backbone.Model.extend({
initialize:
function()
{
...
},
author:
function()
{
...
},
pubDate:
function()
{
...
},
});
var
DocumentRow
=
Backbone.View.extend({
tagName:
"li",
className:
"row",
events:
{
"click
.icon":
"open",
"click
.button.edit":
"openEditDialog"
},
render:
function()
{
...
}
});

62. Example:
Create Extended Objects with Backbone
[Object].extend is used to
“inherit” the built-in
functionality of Backbone
Models, Views, Collections
and Routers
var
Book
=
Backbone.Model.extend({
initialize:
function()
{
...
},
author:
function()
{
...
},
pubDate:
function()
{
...
},
});
var
DocumentRow
=
Backbone.View.extend({
tagName:
"li",
className:
"row",
events:
{
"click
.icon":
"open",
"click
.button.edit":
"openEditDialog"
},
render:
function()
{
...
}
});

63. Balance
Image “Portrait of the children of Charles I” by Anthony Van Dyck from: http://char.txa.cornell.edu/language/principl/principl.htm

64. Balance (art)
The arrangement of elements to ensure that no one part of the work
overpowers other parts, or causes it to feel unstable.
Image of Italian Textile, 18th Centuty from: http://char.txa.cornell.edu/language/principl/principl.htm

65. Balance (API Design):
Weight & Predictability
Browser Feature Tests in
Modernizr
DOM Selection Syntax in
jQuery
Ensure that each
function of your
library exhibits
consistent behavior,
or aids in meeting a
complimentary goal.

66. Example:
Modernizr.geolocation
Modernizr.localstorage
Modernizr.webworkers
Modernizr.canvas
Modernizr.borderradius
Test Browser Capabilities using Modernizr

67. Example:
Modernizr.geolocation
Modernizr.localstorage
Modernizr.webworkers
Modernizr.canvas
Modernizr.borderradius
Test Browser Capabilities using Modernizr
Each property matches an
HTML5/CSS-related API
and returns a boolean

68. Example:
$("#grid")
//
Selects
by
ID
$("ul.nav
>
li")
//
All
LIs
for
UL
w/class
"nav"
$("ul
li:nth-­‐child(2)")
//
2nd
item
in
each
list
Select DOM Elements using jQuery’s Selector Syntax

69. Example:
$("#grid")
//
Selects
by
ID
$("ul.nav
>
li")
//
All
LIs
for
UL
w/class
"nav"
$("ul
li:nth-­‐child(2)")
//
2nd
item
in
each
list
Select DOM Elements using jQuery’s Selector Syntax
Many jQuery Selectors
map directly to equivalent
CSS selectors

70. Proportion
Image “The Fisherman” by Saul Steinberg from: http://char.txa.cornell.edu/language/principl/principl.htm

71. Proportion (art)
A measurement of the size and quantity of elements within a work,
relative to the whole.
Image of Salisbury Cathedral from: http://char.txa.cornell.edu/language/principl/principl.htm

72. Proportion (API Design):
Scope that matches capability
Moment.js
Underscore
Make sure that
every interface of
the library matches
its intended purpose
& that no extraneous
elements exist.

73. Example:
Moment.js is working working with dates... and that’s it
moment().format('dddd');
moment().startOf('hour').fromNow();
moment().format('[Hello from] YYYY'); // Hello from 2013
moment().startOf('day').fromNow();

74. Example:
Moment.js is working working with dates... and that’s it
Moment is designed to make working with the
JavaScript Date object tolerable, and it provides
no functionality beyond that scope.
moment().format('dddd');
moment().startOf('hour').fromNow();
moment().format('[Hello from] YYYY'); // Hello from 2013
moment().startOf('day').fromNow();

75. _.each(["Todd",
"Burke",
"Derick"],
function(name){
alert(name);
});
_.map([1,
2,
3],
function(num){
return
num
*
3;
});
_.isNumber("ten");
//
False
Example:
Underscore.js, designed to add functional programming support to JS

76. _.each(["Todd",
"Burke",
"Derick"],
function(name){
alert(name);
});
_.map([1,
2,
3],
function(num){
return
num
*
3;
});
_.isNumber("ten");
//
False
Example:
Underscore.js, designed to add functional programming support to JS
Underscore provides utility
functions that help devs work
with JS collections, arrays,
functions and objects. Larger API
surface, for a broader purpose.

77. Emphasis
Image of the FlatIron Building from: http://www.greatbuildings.com/

78. Emphasis (art)
The point of focus or interruption of a work. The use of contrast to
cause an aspect of the work to stand out and capture the viewer’s
attention.
Image from: http://char.txa.cornell.edu/language/principl/principl.htm

79. Emphasis (API Design):
Creating a focal point
Plugin development using
jQuery’s fn namespace
Method chaining in jQuery
Object extensibility in
Backbone
Provide a gateway
method that anchors
your library, a chained
or fluent API, or create
extensibility hooks for
consuming devs

80. Example:
jQuery enables a fluent programming style by returning a
jQuery object from most functions.
$(‘ul.first’).find(‘.overdue’)
.css(‘background-­‐color’,‘red’)
.end()
.find(‘.due-­‐soon’)
.css(‘background-­‐color’,
‘yellow’);

81. Example:
jQuery enables a fluent programming style by returning a
jQuery object from most functions.
This style enables devs to accomplish a great
deal of work in a terse, yet readable manner.
$(‘ul.first’).find(‘.overdue’)
.css(‘background-­‐color’,‘red’)
.end()
.find(‘.due-­‐soon’)
.css(‘background-­‐color’,
‘yellow’);

82. (function($)
{
$.fn.kittehfy
=
function()
{
return
this.each(function(idx,
el)
{
var
width
=
el.width,
height
=
el.height;
var
src=
"http://placekitten.com/";
el.src=
src
+
width
+
"/"
+
height;
});
};
})(jQuery);
$("img").kittehfy();
Example:
jQuery plugins are connected to jQuery via the fn (“effin”)
namespace...

83. (function($)
{
$.fn.kittehfy
=
function()
{
return
this.each(function(idx,
el)
{
var
width
=
el.width,
height
=
el.height;
var
src=
"http://placekitten.com/";
el.src=
src
+
width
+
"/"
+
height;
});
};
})(jQuery);
$("img").kittehfy();
Example:
jQuery plugins are connected to jQuery via the fn (“effin”)
namespace...
jQuery Plugins “feel” like
natural extensions to
jQuery itself, and behave
in similar ways

84. Example:
var
Book
=
Backbone.Model.extend({
initialize:
function()
{
...
},
author:
function()
{
...
},
pubDate:
function()
{
...
},
});
var
DocumentRow
=
Backbone.View.extend({
tagName:
"li",
className:
"row",
events:
{
"click
.icon":
"open",
"click
.button.edit":
"openEditDialog"
},
render:
function()
{
...
}
});
Create Extended Objects with Backbone

85. Example:
var
Book
=
Backbone.Model.extend({
initialize:
function()
{
...
},
author:
function()
{
...
},
pubDate:
function()
{
...
},
});
var
DocumentRow
=
Backbone.View.extend({
tagName:
"li",
className:
"row",
events:
{
"click
.icon":
"open",
"click
.button.edit":
"openEditDialog"
},
render:
function()
{
...
}
});
Create Extended Objects with Backbone
[Object].extend is used to
“inherit” the built-in
functionality of Backbone
Models, Views, Collections
and Routers

86. The Four Principles
Unity & Harmony
Balance
Proportion
Emphasis

87. The HORROR!
aka What might go wrong...

88. What might go wrong...
Inconsistency
Disproportionality

89. Imbalance...
Callback signatures on $.map, $.each & $(el).map

90. Imbalance...
Callback signatures on $.map, $.each & $(el).map

91. Imbalance...
var
letters
=
[“a”,
“b”,
“c”,
“d”,
“e”];
Callback signatures on $.map, $.each & $(el).map

92. Imbalance...
var
letters
=
[“a”,
“b”,
“c”,
“d”,
“e”];
$.each(letters,
function(index,
val)
{
console.log(index
+
“:
“
+
val.toUpperCase());
Callback signatures on $.map, $.each & $(el).map

93. Imbalance...
var
letters
=
[“a”,
“b”,
“c”,
“d”,
“e”];
$.each(letters,
function(index,
val)
{
console.log(index
+
“:
“
+
val.toUpperCase());
});
Callback signatures on $.map, $.each & $(el).map

94. Imbalance...
var
letters
=
[“a”,
“b”,
“c”,
“d”,
“e”];
$.each(letters,
function(index,
val)
{
console.log(index
+
“:
“
+
val.toUpperCase());
});
Callback signatures on $.map, $.each & $(el).map

95. Imbalance...
var
letters
=
[“a”,
“b”,
“c”,
“d”,
“e”];
$.each(letters,
function(index,
val)
{
console.log(index
+
“:
“
+
val.toUpperCase());
});
var
uppers
=
$.map(letters,
function(val,
index)
{
return
(val.toUpperCase());
Callback signatures on $.map, $.each & $(el).map

96. Imbalance...
var
letters
=
[“a”,
“b”,
“c”,
“d”,
“e”];
$.each(letters,
function(index,
val)
{
console.log(index
+
“:
“
+
val.toUpperCase());
});
var
uppers
=
$.map(letters,
function(val,
index)
{
return
(val.toUpperCase());
});
Callback signatures on $.map, $.each & $(el).map

97. Imbalance...
var
letters
=
[“a”,
“b”,
“c”,
“d”,
“e”];
$.each(letters,
function(index,
val)
{
console.log(index
+
“:
“
+
val.toUpperCase());
});
var
uppers
=
$.map(letters,
function(val,
index)
{
return
(val.toUpperCase());
});
Callback signatures on $.map, $.each & $(el).map

98. Imbalance...
var
letters
=
[“a”,
“b”,
“c”,
“d”,
“e”];
$.each(letters,
function(index,
val)
{
console.log(index
+
“:
“
+
val.toUpperCase());
});
var
uppers
=
$.map(letters,
function(val,
index)
{
return
(val.toUpperCase());
});
$(‘li’).map(function(index,
val)
{
//WAT
});
Callback signatures on $.map, $.each & $(el).map

99. Imbalance...
var
letters
=
[“a”,
“b”,
“c”,
“d”,
“e”];
$.each(letters,
function(index,
val)
{
console.log(index
+
“:
“
+
val.toUpperCase());
});
var
uppers
=
$.map(letters,
function(val,
index)
{
return
(val.toUpperCase());
});
$(‘li’).map(function(index,
val)
{
//WAT
});
Callback signatures on $.map, $.each & $(el).map
Not only do $.map and $.each diverge, but $.map and $(el).map order the
callback params differently, depending on how the method is called.

100. Proportion: Too
Large or Too Small...

101. Image of Fred Brooks from: http://www-set.win.tue.nl/UnsungHeroes/files/PTERA-Kosten-Poel.jpg

102. Image of Fred Brooks from: http://www-set.win.tue.nl/UnsungHeroes/files/PTERA-Kosten-Poel.jpg
“Van der Poel designed a computer with only
one operation code...”

103. Image of Fred Brooks from: http://www-set.win.tue.nl/UnsungHeroes/files/PTERA-Kosten-Poel.jpg
“... Every instruction carried out the same
operation. He demonstrated the sufficiency of
his operation—his machine could do anything
any other computer could do...”

104. Image of Fred Brooks from: http://www-set.win.tue.nl/UnsungHeroes/files/PTERA-Kosten-Poel.jpg
“...And yet it was very difficult to program....”

105. Image of Fred Brooks from: http://www-set.win.tue.nl/UnsungHeroes/files/PTERA-Kosten-Poel.jpg
“...the delight that came from using it was
similar to... working out a crossword puzzle—
a construct of intentional complexity and no
intended utility.”
- Fred Brooks

106. AwesomeLib.do(prams);

107. AwesomeLib.do(prams);
We can all agree
that this is bad

108. jQuery();

109. jQuery();
Then, so is this...

110. Overloads on the jQuery()
method...

111. jQuery(
selector
[,
context]
)
//
Select
Overloads on the jQuery()
method...

112. jQuery(
selector
[,
context]
)
//
Select
jQuery(
element
)
//
Wrap
Overloads on the jQuery()
method...

113. jQuery(
selector
[,
context]
)
//
Select
jQuery(
element
)
//
Wrap
jQuery(
object
)
//
Wrap
Overloads on the jQuery()
method...

114. jQuery(
selector
[,
context]
)
//
Select
jQuery(
element
)
//
Wrap
jQuery(
object
)
//
Wrap
jQuery()
//
Empty
$
Object
Overloads on the jQuery()
method...

115. jQuery(
selector
[,
context]
)
//
Select
jQuery(
element
)
//
Wrap
jQuery(
object
)
//
Wrap
jQuery()
//
Empty
$
Object
jQuery(
elementArray
)
//
Wrap
Overloads on the jQuery()
method...

116. jQuery(
selector
[,
context]
)
//
Select
jQuery(
element
)
//
Wrap
jQuery(
object
)
//
Wrap
jQuery()
//
Empty
$
Object
jQuery(
elementArray
)
//
Wrap
jQuery(
jQuery
object
)
//
Clone
Overloads on the jQuery()
method...

117. jQuery(
selector
[,
context]
)
//
Select
jQuery(
element
)
//
Wrap
jQuery(
object
)
//
Wrap
jQuery()
//
Empty
$
Object
jQuery(
elementArray
)
//
Wrap
jQuery(
jQuery
object
)
//
Clone
jQuery(
html
[,
ownerDocument
]
)
//
Create
DOM
Elements
Overloads on the jQuery()
method...

118. jQuery(
selector
[,
context]
)
//
Select
jQuery(
element
)
//
Wrap
jQuery(
object
)
//
Wrap
jQuery()
//
Empty
$
Object
jQuery(
elementArray
)
//
Wrap
jQuery(
jQuery
object
)
//
Clone
jQuery(
html
[,
ownerDocument
]
)
//
Create
DOM
Elements
jQuery
(
html,
props
)
//
Create
DOM
Elements
Overloads on the jQuery()
method...

119. jQuery(
selector
[,
context]
)
//
Select
jQuery(
element
)
//
Wrap
jQuery(
object
)
//
Wrap
jQuery()
//
Empty
$
Object
jQuery(
elementArray
)
//
Wrap
jQuery(
jQuery
object
)
//
Clone
jQuery(
html
[,
ownerDocument
]
)
//
Create
DOM
Elements
jQuery
(
html,
props
)
//
Create
DOM
Elements
jQuery
(
callback
)
//
Bind
DOM
loaded
function
Overloads on the jQuery()
method...

120. jQuery(
selector
[,
context]
)
//
Select
jQuery(
element
)
//
Wrap
jQuery(
object
)
//
Wrap
jQuery()
//
Empty
$
Object
jQuery(
elementArray
)
//
Wrap
jQuery(
jQuery
object
)
//
Clone
jQuery(
html
[,
ownerDocument
]
)
//
Create
DOM
Elements
jQuery
(
html,
props
)
//
Create
DOM
Elements
jQuery
(
callback
)
//
Bind
DOM
loaded
function
Overloads on the jQuery()
method...
11 ways to call
jQuery, with 6
different contexts!

121. Now, for a question...

122. jQuery: Good
API Design or
Bad API
Design?
Image from: http://laughingsquid.com/wp-content/uploads/Kevin-Bacon.jpg

123. jQuery: Good
API Design or
Bad API
Design?
Image from: http://laughingsquid.com/wp-content/uploads/Kevin-Bacon.jpg
A baseline example of “Good...”

124. jQuery: Good
API Design or
Bad API
Design?
Image from: http://laughingsquid.com/wp-content/uploads/Kevin-Bacon.jpg
A baseline example of “Good...”

126. YES

127. Here’s the
point...
Image from: http://laughingsquid.com/wp-content/uploads/Kevin-Bacon.jpg

128. Building and
evolving a useful
API is hard...
Image from: http://www.ibiblio.org/xml/slides/xmlone/london2002/schemas/83.html

129. ...you won’t always
get it right.
Image from: gorestruly.com2011/09/30/rotting-americana-the-winchester-mystery-house/

130. But hey, jQuery’s not perfect...

131. ... so you don’t have to be either.

132. Questions?
@BrandonSatrom
brandon@kendoui.com