UBER: A New Hypermedia Format for APIs

Mike Amundsen, author of "Building Hypermedia APIs with HTML5 and Node" and "RESTful Web APIs", has recently announced a new media type design that he's been working on. It's called UBER hypermedia, which stands for "Uniform Basis for Exchanging Representations." Mike describes UBER as follows:

The Uber message format is a minimal read/write hypermedia type designed to support simple state transfers and ad-hoc hypermedia-based transitions. This document describes both the XML and JSON variants of the format and provides guidelines for supporting Uber messages over the HTTP protocol.

There's been a Cambrian explosion of hypermedia formats lately: HAL, JSON API, Hydra, and others. So why make another one? Mike responds:

I think we need lots of experiments in order to generate useful messages designs in this space. I'm happy to see that we've had more hypermedia designs registered with the IANA in the last three years than in the previous 10. The more designs we see the more likely we are to discover the principles and practices of great hypermedia designs. UBER is just one more offering to help advance the practice.

One of the interesting things about UBER is that it's protocol-agnostic. Most media types make an assumption that they'll be built on top of HTTP, but UBER can work with many different protocols. Mike sees the possibility of a post-HTTP world, and UBER will be able to take advantage:

HTTP has been around for over twenty years and has been a dominant application-level protocol for more than fifteen years. Since most of what we know of as "the Web" has always relied primarily on this single protocol, it is tough for some to remember a time when we didn't know if HTTP would take off and even harder to imagine that HTTP might someday no longer be the most popular way to transfer data around the world. On the other hand, I assume that HTTP will someday be superseded by some other app-level protocol; maybe in 10, 20 or more years hence. So I am experimenting now with designs that take that into account.

One area that's still being explored in the media design space is error messages. There are a few attempts to make a generic error media type, but Mike's designs tend to include their own errors inline. Mike elaborates on that choice:

There are two reasons I did not use Ben Longden's vnd.error media type to express errors within my UBER design. The first is that vnd.error is not an IANA-registered design. While this is not a requirement or indication of a good design, I don't want to create a dependency within UBER on a non-registered message design.

Second, I think it is important to include error information as a native aspect of hypermedia message design and not as an ancillary or secondary feature. Also, I don't want to set up a requirement that UBER media type clients MUST also support another media type in order to get their work done.

Mike has contended that UBER "doesn't support object serialization," yet that's how most people think of APIs. He expands at length about why this is the case:

So far none of my hypermedia designs support direct serialization from code-based objects into message-based state representations. One reason is my aim to design message models that are orthogonal to any source code model. I want my designs to be equally usable in any programming language.

Over the last few years, a single language (JavaScript) has dominated developer thinking. So much that most devs assume that state representations should look just like JavaScript source code. That's not how the first decade of the Web worked. HTML and XML are both source code agnostic designs. I think there is some great value in that POV.

Also, when it comes to large scale implementations -- at the system level -- I favor patterns that promote sharing state, not objects. This is especially valuable in cases where those writing consumer applications and those writing provider applications are separated by time and space. It is much easier to get agreement on data elements than on object models. Essentially, in serialization-based designs, object models become the "cost of entry" to building an app. Everyone needs to agree on the object model before you can build an app. And object models change over time; more often than simple data elements. Creating designs that lower the amount of a priori knowledge -- that are based on state rather than objects -- is one of the ways to promote the principle of serendipity on the Web described by Stu Charlton in 2007.

Lastly, my recent readings on how humans and other animals interact with the world show that we first perceive raw data and only after acquiring the data do we compare that to models in our heads and turn the data into useful information. It's a two-stage process. I like creating message designs that lead developers into writing apps that mimic that process of interacting with things around us first, and converting that data into local models second. We don't need shared object models to communicate with each other, just shared data.

As the hypermedia space continues to grow and change, new media types will get created to improve on older formats. UBER's simplicity, focus, and de-emphasis on HTTP make for a novel entrance into the space.