min read

A Path for High-Level Web APIs

In 2013 the Extensible Web Manifesto was formed and it has influenced how web APIs are developed ever since. For those who aren't familiar, the manifesto roughly follows this model:

  1. Develop low-level APIs that describe existing features of the web.
  2. Allow developers time to iterate on these APIs, creating libraries that provide a more high-level abstraction.
  3. Take what has worked well from library and standardize new high-level web APIs.

This has become the defacto way web APIs are developed ever since.

Unfortunately step 3 has not been followed through on as much as you would hope.

Why High-Level APIs

Before getting into what has gone wrong, let me first make the case for high-level APIs. It's unfortunate that the case needs to be made, but I feel that it does. Despite the Extensible Web Manifesto explicitly encouraging high-level APIs to be developed from the work libraries have done, it has become common-place in web spec chatter to assume that high-level APIs are not necessary if a low-level API exists to fit the use-case.

High-level APIs are important for 3 primary reasons:

  1. High-level APIs are more productive than low-level APIs. You can get more accomplished when you do not need to muck in the details of how to accomplish a completely normal thing.
  2. High-level APIs have a lower learning curve, which invites in more developers (both those new to using the web and those who don't have the time to learn a million low-level APIs, two extremely important segments).
  3. Libraries are not a substitute for high-level built-in APIs because every page has a limit on the number of libraries you can use.

(3) is the most important one here because you can, and many do, discount (1) and (2) with the justification that libraries can serve the needs.

However it is a simple reality that there is a marginal cost to adding libraries to any web page. That cost has to be weighed each time we do so. If we ignore the cost the user experience suffers. The only solution is for the platform to provide commonly needed high-level APIs.

High-Level API Teams

With that I'd like to introduce the idea of high-level API teams. We have some examples of this already such as the Maps 4 HTML community group and Open UI.

A high-level API team's job is to follow through on the steps of the extensible web manifesto completely. Today the question is often raised:

How can we improve this use-case today.

With the high-level team concept the question is inverted to:

What would be the absolute best solution to this use-case and what intermediate steps would be required to achieve it?

This admittedly means that a high-level API team is a long term process. Potentially very long, multi-decade perhaps! Even the most optimistic amongst us will become disenchanted over such a long period of time.

Having high-level API teams solves for fatigue by allowing people to cycle in and out. If a person is only interested in the first, low-level API they can join the team and craft that API, and then leave. Others might join the team only when the high-level API is ready to be designed.

Ultimately what the high-level API team concept achieves is continued focus on the goal. It is the road, the railroad tracks, that point an exhaustingly long process toward where it needs to go. Without such a structure it is the wild west, which is what we have today.

Next Steps

I understand no one is going to read this blog post and start implementing what is advocated here. I need to get involved directly. In the near future I plan on forming high-level API teams for:

If you are interested in either of these high-level features and would like to join me, please reach out (@matthewcp) and let me know. I'll be posting more about these API teams when there is more to talk about.