Saturday, 17 April 2010

API Design For The Masses

On Monday I gave a talk at the Victora University computer science department which I called "API Design For The Masses". I've put the slides online. The premise is that designing specifications for the Web requires you to make different decisions than in the "good old days" when a relatively small number of professionals were writing specifications and implementing both sides of those specifications. I give eight design principles for Web-scale specs, mostly based on examples.

The contents should not be surprising to anyone involved with the WHATWG. I didn't invent these principles, I just wanted to summarize my version of some of what the community already knows.

These are my principles:

  1. Try to define behaviour for all inputs. Avoid "undefined" behaviours. Simplify or eliminate "fatal" behaviours.
  2. Specs that contradict entrenched practice must be changed to match it. If following the spec harms users, that part of the spec is worthless.
  3. Standardization and implementation must happen concurrently. You need a fast feedback loop, which means you need to be able to update the spec frequently and with low latency.
  4. Provide non-standard/pre-standard extensions, but use syntax to ensure authors know they're non-standard.
  5. Favour evolution over revolution if possible.
  6. Aim for forward and backward compatibility (with graceful degradation). Avoid versioning.
  7. Encourage conditional content to use detection of features, not detection of implementations. Provide mechanisms for such conditionals.
  8. Only add features where authors can see and correct their mistakes. Invisible metadata doesn't work.


  1. Ahhhh, yes. The sense of loss we feel is perhaps best summed up by paraphrasing Hunter S. Thompson: "So now, less than five years later, you can go and read the XHTML spec, and with the right kind of eyes you can almost see the high-water mark — that place where the wave finally broke and rolled back."

  2. 9. When designing a markup language from scratch, make it strict and allow the principles of API design to refine it into something more permissive, rather than the other way round.
    Especially do not make the mistake of
    a. starting with something permissive,
    b. wondering why everyone uses it but no-one respects it
    c. attempting to fix it by introducing a strict version
    d. insisting that the new strict version must stay strict
    e. improving the new strict version by introducing a new, non-compatible strict version

  3. Addressing points 6 & 7, I'd like a bit of css syntax which could act as a conditional to predicate a rule. This conditional would simply be is the argument a supported css rule or not. (my vocabulary is no doubt lacking here)
    For instance, some browsers support border-image, and others don't. It would be nice if I could entire support a different set of styling rules if rounded borders aren't supported. Thus I could have
    supported(border-image) blockquote { border-image: ...; blah; blah; blah; }
    not_supported(border-image) blockquote { something; completely; different }
    Unrelated to this, I just noticed that if I use Preview for my comment, the preview page clears out the name/email/url/comments fields.

  4. Another one I would add is "design your language to make sense to amateurs first, then evolve it to fit professionals". Doing the reverse is so hard as to be near impossible.

    Dear whom,
    We are a lab team for studying interface.
    We think our technology will be good combine with the cr-48& chrome os& igoogle widget service.
    We recomend our techonolgy which can substitute a mouse and a keyboard, also it could be used as multi view.
    If you click above website, you can get more information and figure out our ideas. So, we would like recommend you.
    If you have any questions or interests, please access website:
    also, If you want to confirm our patent or prototype, send email to us:
    Thank you for your time.
    I am looking forward to meet you.
    Repusy Lab.(South Korea)