Secrets of Awesome JavaScript API Design

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.

Transcript

1. Secrets of Awesome JavaScript API Design Brandon Satrom @BrandonSatrom brandon@KendoUI.com Friday, May 24, 13
2. Read it @ bit.ly/ ZS5VYv Friday, May 24, 13
3. 3 Big Ideas Friday, May 24, 13
4. Three ideas... Friday, May 24, 13
5. Three ideas... 1.APIs are “Developer UX” Friday, May 24, 13
6. Three ideas... 1.APIs are “Developer UX” 2.API Design is a universal practice Friday, May 24, 13
7. Three ideas... 1.APIs are “Developer UX” 2.API Design is a universal practice 3.API Design is a “principle-driven” art form Friday, May 24, 13
8. What is design? Friday, May 24, 13
9. What is design? “form[ing] a plan or scheme of [some thing]… for later execution” - Oxford English Dictionary Friday, May 24, 13
10. Design is universal Friday, May 24, 13
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/ Friday, May 24, 13
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/ Friday, May 24, 13
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/ Friday, May 24, 13
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/ Friday, May 24, 13
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 Friday, May 24, 13
16. We apply design practices to User Interfaces... Images from: http://pinterest.com/fromupnorth/gui/ Friday, May 24, 13
17. We call this practice, User Experience (UX) design... Images from: http://pinterest.com/fromupnorth/gui/ Friday, May 24, 13
18. What about API Design? Friday, May 24, 13
19. API Design is “Developer UX” Friday, May 24, 13
20. API Design is not JUST For Library Authors... Friday, May 24, 13
21. ...modular JS is written to be consumed... Friday, May 24, 13
22. ...the number of consumers is irrelevant. Images from flickr.com/photos/powi/ Friday, May 24, 13
23. In JavaScript, API design is critically important... Friday, May 24, 13
24. Dynamic Language... Friday, May 24, 13
25. Anonymity of consumers... http://i.qkme.me/3qesq1.jpg Friday, May 24, 13
26. Ambiguity of Requirements... Friday, May 24, 13
27. Your users are smart... Friday, May 24, 13
28. Yeah, but my users won’t... Image from: http://idratherbewriting.com/wp-content/uploads/2012/08/rtfmtractor.jpg Friday, May 24, 13
29. Yeah, but my users won’t... Image from: http://idratherbewriting.com/wp-content/uploads/2012/08/rtfmtractor.jpg Friday, May 24, 13
30. A Tale of Ice & Water Friday, May 24, 13
31. A Tale of Ice & Water Friday, May 24, 13
32. A Tale of Ice & Water Friday, May 24, 13
33. A Tale of Ice & Water Friday, May 24, 13
34. A Tale of Ice & Water Friday, May 24, 13
35. In Industrial Design, this is NOT an acceptable answer... Image from: http://idratherbewriting.com/wp-content/uploads/2012/08/rtfmtractor.jpg Friday, May 24, 13
36. ... how is Software Different? Image from: http://www.globalnerdy.com/wordpress/wp-content/uploads/2010/05/makeabetterfm.jpg Friday, May 24, 13
37. ... how is Software Different? Image from: http://www.globalnerdy.com/wordpress/wp-content/uploads/2010/05/makeabetterfm.jpg It’s Not. Friday, May 24, 13
38. Friday, May 24, 13
39. Your users are smart... Friday, May 24, 13
40. http://thebus.net/sites/default/files/americas-next-top-hipster.jpg Friday, May 24, 13
41. ...but they are NOT... you. http://thebus.net/sites/default/files/americas-next-top-hipster.jpg Friday, May 24, 13
42. Design the “pit of success” Image from: http://darrell.mozingo.net/2011/06/26/the-pit-of-success/ Friday, May 24, 13
43. Example: $("article.blogPost").fadeIn(); Use jQuery to select all article tags with the class “blogPost” Friday, May 24, 13
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; } Friday, May 24, 13
45. Goals of API Design Be Self-Describing Prevent Errors Make Users Fast Image from: http://elliottbrown.files.wordpress.com/2012/04/sandcastles.png Friday, May 24, 13
46. Friday, May 24, 13
47. Goals are not enough... Friday, May 24, 13
48. Friday, May 24, 13
49. ...we need guiding principles... Friday, May 24, 13
50. Principles, not Rules Friday, May 24, 13
51. Principles, not Rules Rules are rote, often applied without context Principles encourage application of context Friday, May 24, 13
52. Principles Found in Physical Media Images from: http://char.txa.cornell.edu/language/principl/principl.htm & http://www.greatbuildings.com/ Friday, May 24, 13
53. Principles on display in popular libraries... Backbone jQuery Kendo UI Modernizr Moment.js Underscore Friday, May 24, 13
54. WARNING! This is ART, not SCIENCE Friday, May 24, 13
55. The Four Principles Unity & Harmony Balance Proportion Emphasis Friday, May 24, 13
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 Friday, May 24, 13
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 Friday, May 24, 13
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 Friday, May 24, 13
59. Example: Create Kendo UI Widgets from jQuery-selected DOM Elements $("ul.tree").kendoTreeView(); $("ul.panel").kendoPanelBar(); $("div").kendoGrid(); Friday, May 24, 13
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(); Friday, May 24, 13
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()  {  ...  } }); Friday, May 24, 13
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()  {  ...  } }); Friday, May 24, 13
63. Balance Image “Portrait of the children of Charles I” by Anthony Van Dyck from: http://char.txa.cornell.edu/language/principl/principl.htm Friday, May 24, 13
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 Friday, May 24, 13
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. Friday, May 24, 13
66. Example: Modernizr.geolocation Modernizr.localstorage Modernizr.webworkers Modernizr.canvas Modernizr.borderradius Test Browser Capabilities using Modernizr Friday, May 24, 13
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 Friday, May 24, 13
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 Friday, May 24, 13
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 Friday, May 24, 13
70. Proportion Image “The Fisherman” by Saul Steinberg from: http://char.txa.cornell.edu/language/principl/principl.htm Friday, May 24, 13
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 Friday, May 24, 13
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. Friday, May 24, 13
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(); Friday, May 24, 13
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(); Friday, May 24, 13
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 Friday, May 24, 13
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. Friday, May 24, 13
77. Emphasis Image of the FlatIron Building from: http://www.greatbuildings.com/ Friday, May 24, 13
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 Friday, May 24, 13
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 Friday, May 24, 13
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’); Friday, May 24, 13
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’); Friday, May 24, 13
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... Friday, May 24, 13
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 Friday, May 24, 13
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 Friday, May 24, 13
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 Friday, May 24, 13
86. The Four Principles Unity & Harmony Balance Proportion Emphasis Friday, May 24, 13
87. The HORROR! aka What might go wrong... Friday, May 24, 13
88. What might go wrong... Inconsistency Disproportionality Friday, May 24, 13
89. Inconsistency... Callback signatures on $.map, $.each & $(el).map Friday, May 24, 13
90. Inconsistency... Callback signatures on $.map, $.each & $(el).map Friday, May 24, 13
91. Inconsistency... var  letters  =  [“a”,  “b”,  “c”,  “d”,  “e”]; Callback signatures on $.map, $.each & $(el).map Friday, May 24, 13
92. Inconsistency... var  letters  =  [“a”,  “b”,  “c”,  “d”,  “e”]; $.each(letters,  function(index,  val)  {    console.log(index  +  “:  “  +  val.toUpperCase()); Callback signatures on $.map, $.each & $(el).map Friday, May 24, 13
93. Inconsistency... var  letters  =  [“a”,  “b”,  “c”,  “d”,  “e”]; $.each(letters,  function(index,  val)  {    console.log(index  +  “:  “  +  val.toUpperCase()); });   Callback signatures on $.map, $.each & $(el).map Friday, May 24, 13
94. Inconsistency... var  letters  =  [“a”,  “b”,  “c”,  “d”,  “e”]; $.each(letters,  function(index,  val)  {    console.log(index  +  “:  “  +  val.toUpperCase()); });   Callback signatures on $.map, $.each & $(el).map Friday, May 24, 13
95. Inconsistency... 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 Friday, May 24, 13
96. Inconsistency... 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 Friday, May 24, 13
97. Inconsistency... 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 Friday, May 24, 13
98. Inconsistency... 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 Friday, May 24, 13
99. Inconsistency... 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. Friday, May 24, 13
100. Proportion: Too Large or Too Small... Friday, May 24, 13
101. AwesomeLib.do(prams); Friday, May 24, 13
102. AwesomeLib.do(prams); We can all agree that this is bad Friday, May 24, 13
103. jQuery(); Friday, May 24, 13
104. jQuery(); Then, so is this... Friday, May 24, 13
105. Overloads on the jQuery() method... Friday, May 24, 13
106. jQuery(  selector  [,  context]  )  //  Select Overloads on the jQuery() method... Friday, May 24, 13
107. jQuery(  selector  [,  context]  )  //  Select jQuery(  element  )  //  Wrap Overloads on the jQuery() method... Friday, May 24, 13
108. jQuery(  selector  [,  context]  )  //  Select jQuery(  element  )  //  Wrap jQuery(  object  )  //  Wrap Overloads on the jQuery() method... Friday, May 24, 13
109. jQuery(  selector  [,  context]  )  //  Select jQuery(  element  )  //  Wrap jQuery(  object  )  //  Wrap jQuery()  //  Empty  $  Object Overloads on the jQuery() method... Friday, May 24, 13
110. jQuery(  selector  [,  context]  )  //  Select jQuery(  element  )  //  Wrap jQuery(  object  )  //  Wrap jQuery()  //  Empty  $  Object jQuery(  elementArray  )  //  Wrap Overloads on the jQuery() method... Friday, May 24, 13
111. 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... Friday, May 24, 13
112. 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... Friday, May 24, 13
113. 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... Friday, May 24, 13
114. 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... Friday, May 24, 13
115. 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! Friday, May 24, 13
116. Building and evolving a useful API is hard... Image from: http://www.ibiblio.org/xml/slides/xmlone/london2002/schemas/83.html Friday, May 24, 13
117. ...you won’t always get it right. Image from: gorestruly.com2011/09/30/rotting-americana-the-winchester-mystery-house/ Friday, May 24, 13
118. But hey, jQuery’s not perfect... Friday, May 24, 13
119. ... so you don’t have to be either. But hey, jQuery’s not perfect... Friday, May 24, 13
120. What are we building anyway? Image of Fred Brooks from: http://www-set.win.tue.nl/UnsungHeroes/files/PTERA-Kosten-Poel.jpg Friday, May 24, 13
121. Image of Fred Brooks from: http://www-set.win.tue.nl/UnsungHeroes/files/PTERA-Kosten-Poel.jpg Friday, May 24, 13
122. 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...” Friday, May 24, 13
123. 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...” Friday, May 24, 13
124. 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....” Friday, May 24, 13
125. 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 Friday, May 24, 13
126. Let’s build great art Image from: http://laughingsquid.com/wp-content/uploads/Kevin-Bacon.jpg Friday, May 24, 13
127. Slides bit.ly/JSAPIDesign @BrandonSatrom brandon@kendoui.com Fluent Office Hours - 11:50 - 12:30 East Lounge (Table C) Friday, May 24, 13