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.
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.
On generic error representations
It's great to see people like Mike experimenting with hypermedia formats like Uber. I really like his point that we need to be creating more and pushing them out there for others to use - let's see what sticks.
vnd.error is a generic error type - it was always based on the Hal specification and has relatively recently moved to being entirely compatible with Hal. Once Hal itself is out of draft status, it too will be moved towards being an IANA registered design.
There's also a question of why register its own media type if it's just Hal? I hope that the profile relation will go a long way to help people use generic media formats and add documented domain specific behaviour whilst remaining compatible with generic tooling (and of course, specific tooling that understands what is defined by the profile information).
Errors being native to the message design is also really interesting. Perhaps vnd.error could become the 'native' way for Hal based API's - but we're still working out what will stick.
Brandon Holt, Preston Briggs, Luis Ceze, Mark Oskin May 21, 2015
Kai Kreuzer, Olaf Weinmann May 21, 2015