Skip to main content

What can wonky APIs tell us about the web?

  • Posted

A few days ago, Misty posted something that caught my eye:

Misty @misty@digipres.club

Finding myself asking if there's ever been a wonkier official browser API than canPlayType

The HTMLMediaElement.canPlayType API tells you how likely it is that a browser can play media with a given MIME type, but the response is unusual. The word “likely” is important here, because it’s not a simple yes/no answer. The possible responses are:

A ternary, probabilistic response is already a bit weird; the return values double down on the weirdness. A clearer set of return values would be "no", "probably" and "unknown".

But when thinking of wonky web APIs, my mind went somewhere else: to History.pushState() and replaceState(). These APIs are for manipulating your browser history, and take an unused parameter which you have to pass but do absolutely nothing.

Here’s the description of pushState from MDN (emphasis mine):

The pushState() method of the History interface adds an entry to the browser’s session history stack.

Syntax:

    pushState(state, unused)
    pushState(state, unused, url)

Parameters:

  • state – The state object is a JavaScript object which is associated with the new history entry created by pushState(). […]
  • unused – This parameter exists for historical reasons, and cannot be omitted; passing an empty string is safe against future changes to the method.
  • url – The new history entry’s URL.

This begs the question: what historical reasons? Why does an API supported by every major browser have a parameter that nobody uses?

The History API was designed for use with single-page applications (SPAs) – sites that only load a single page, then use JavaScript to update the contents of a page, rather than loading a new page every time something changes. Using SPAs can make a site faster, because they only have to load the part of a page that’s changed, but they also break the behaviour of the browser’s “back” and “forward” buttons.

From the user’s point of view, they click links and the page changes, so if they click the “back” button, they expect to go back to their previous state.

But the browser only records a single history event, when the user first loads the SPA – all the in-page updates using JavaScript don’t register as new pages. When the user clicks the “back” button, the browser will take them to whatever page they were looking at before they opened the SPA.

Using pushState() and replaceState() allows an app to create synthetic history entries, so the “back” and “forward” buttons can step the user through the pages they’ve seen within the SPA.

The pushState() API first appeared in a draft HTML5 spec in January 2008, with three parameters:

The title parameter was always “advisory”, and in practice most browsers completely ignored the parameter, to avoid the confusion of mismatched titles in the browser UI and session history.

It soon became clear that the title parameter was pointless, but it was already too late to change. Lots of sites were built as single-page applications and already using the new pushState and replaceState APIs, and breaking those sites was unacceptable.

The argument could be neither removed nor made optional. If you removed it, you’d break sites that used the three-parameter pushState(state, title, url). If you made it optional, its position in the middle of the signature would leave browsers unable to distinguish between pushState(state, url) and pushState(state, title).

Instead, the spec was updated to rename the parameter to unused and clarify it has no effect.

This wonky API reflects the challenge of designing for the web: it’s difficult to design APIs without seeing how they’re used on real world websites, but then it’s too late to make changes in response to feedback. The web goes to incredible lengths to preserve backward compatibility, and it’s the ultimate form of “anything described as a prototype will get shipped in production”.

The longevity of vanilla web technology is why I keep using static websites for my media archives – more than anything else in my career in tech, web technology is what lasts.