Home > Web Designer Wall > HTML APIs: What They Are And How To Design A Good One

HTML APIs: What They Are And How To Design A Good One

As JavaScript developers, we often forget that not everyone has the same knowledge as us. It’s called the curse of knowledge: When we’re an expert on something, we cannot remember how confused we felt as newbies. We overestimate what people will find easy. Therefore, we think that requiring a bunch of JavaScript to initialize or configure the libraries we write is OK. Meanwhile, some of our users struggle to use them, frantically copying and pasting examples from the documentation, tweaking them at random until they work.

You might be wondering, “But all HTML and CSS authors know JavaScript, right?” Wrong. Take a look at the results of my poll, which is the only data on this I’m aware of. (If you know of any proper studies on this, please mention them in the comments!)

Poll: “How comfortable are you with JavaScript?” (22 January 2016)

One in two people who write HTML and CSS is not comfortable with JavaScript. One in two. Let that sink in for a moment.

As an example, look at the following code to initialize a jQuery UI autocomplete, taken from its documentation:

<div class="ui-widget">      <label for="tags">Tags: </label>      <input id="tags">  </div>  
$( function() {      var availableTags = [          "ActionScript",          "AppleScript",          "Asp",          "BASIC",          "C"      ];      $( "#tags" ).autocomplete({          source: availableTags      });  } );  

This is easy, even for people who don’t know any JavaScript, right? Wrong. A non-programmer would have all sorts of questions going through their head after seeing this example in the documentation. “Where do I put this code?” “What are these braces, colons and brackets?” “Do I need them?” “What do I do if my element does not have an ID?” And so on. Even this tiny snippet of code requires people to understand object literals, arrays, variables, strings, how to get a reference to a DOM element, events, when the DOM is ready and much more. Things that seem trivial to programmers can be an uphill battle to HTML authors with no JavaScript knowledge.

Now consider the equivalent declarative code from HTML5:

<div class="ui-widget">      <label for="tags">Tags: </label>      <input id="tags" list="languages">      <datalist id="languages">          <option>ActionScript</option>          <option>AppleScript</option>          <option>Asp</option>          <option>BASIC</option>          <option>C</option>      </datalist>  </div>  

Not only is this much clearer to anyone who can write HTML, it is even easier for programmers. We see that everything is set in one place, no need to care about when to initialize, how to get a reference to the element and how to set stuff on it. No need to know which function to call to initialize or which arguments it accepts. And for more advanced use cases, there is also a JavaScript API in place that allows all of these attributes and elements to be created dynamically. It follows one of the most basic API design principles: It makes the simple easy and the complex possible.

This brings us to an important lesson about HTML APIs: They would benefit not only people with limited JavaScript skill. For common tasks, even we, programmers, are often eager to sacrifice the flexibility of programming for the convenience of declarative markup. However, we somehow forget this when writing a library of our own.

So, what is an HTML API? According to Wikipedia, an API (or application programming interface) is “is a set of subroutine definitions, protocols, and tools for building application software.” In an HTML API, the definitions and protocols are in the HTML itself, and the tools look in HTML for the configuration. HTML APIs usually consist of certain class and attribute patterns that can be used on existing HTML. With Web Components, even custom element names are game, and with the Shadow DOM, those can even have an entire internal structure that is hidden from the rest of the page’s JavaScript or CSS. But this is not an article about Web Components; Web Components give more power and options to HTML API designers; but the principles of good (HTML) API design are the same.

HTML APIs improve collaboration between designers and developers, lift some work from the shoulders of the latter, and enable designers to create much higher-fidelity mockups. Including an HTML API in your library does not just make the community more inclusive, it also ultimately comes back to benefit you, the programmer.

Not every library needs an HTML API. HTML APIs are mostly useful in libraries that enable UI elements such as galleries, drag-and-drop, accordions, tabs, carousels, etc. As a rule of thumb, if a non-programmer cannot understand what your library does, then your library doesn’t need an HTML API. For example, libraries that simplify or help to organize code do not need an HTML API. What kind of HTML API would an MVC framework or a DOM helper library even have?

So far, we have discussed what an HTML API is, why it is useful and when it is needed. The rest of this article is about how to design a good one.

Read Full Article

The WebRecital is a dedicated User Interface/User Experience professionals who come together to provide design and research workshops, portfolio reviews, and educational outreach to the greater Seattle area.

Leave a Reply

Your email address will not be published. Required fields are marked *