Amazon Chooses HAL Media Type for AppStream API

Amazon has released a new API, the AppStream API, which allows you to programmatically manage applications hosted on the Amazon AppStream platform. For this API, they chose to build it with the HAL media type. HAL is a minimalistic hypermedia enabled media type for building machine-to-machine APIs. Amazon is one of the largest organizations to choose hypermedia as a technique for a public-facing product.

While hypermedia APIs are a hot topic in the API space, advocates are often asked about its real-world applicability. While there has been an explosion of research and debate on the technique, hypermedia APIs make up a small fraction of the current API ecosystem. Amazon's CEO, Jeff Bezos, famously required his teams to build products in an SOA style, leading to a large number of internal and external APIs. This vote of confidence in hypermedia via HAL from one of tech's biggest companies should hearten hypermedia enthusiasts.

One question that the hypermedia community is currently grappling with is documentation. The traditional answer to documenting hypermedia services consists of providing a media type definition and nothing more. This approach is significantly different than other architectural styles, and so the community has been working on other strategies to assist bridging this gap.

The AppStream API team chose to document the API in four major sections: header values, error codes, top-level resources, and link relations. This is very different from more traditional RESTful services, which focus on combinations of HTTP status codes, URLs, and parameters. This approach is very close to the traditional hypermedia approach. On the HAL-discuss mailing list, a place for HAL users to talk about the specification and its uses, Andrés Freyría Cedeño said this:

My gut reaction to the docs were along the lines of "this would be sufficient documentation if hypermedia APIs were the norm". Given the current state of art though, I don't think there are enough ancillary resources for developers to work with.

We'll see how this trend continues as hypermedia becomes a more established API pattern.

HAL is a media type currently undergoing standardization by the IETF. Originally authored by Mike Kelly, HAL is focused on providing a simple, easy to understand set of conventions to XML and JSON for resources to link to one another.

Here's a sample HAL response, from the draft:

{
     "_links": {
       "self": { "href": "/orders/523" },
       "warehouse": { "href": "/warehouse/56" },
       "invoice": { "href": "/invoices/873" }
     },
     "currency": "USD",
     "status": "shipped",
     "total": 10.20
   }

HAL defines two reserved top-level properties, _links and _embedded. You can see _links here. Inside of this object, HAL standardizes the way that links are made. In this example, you can see links for an imaginary "orders" resource, which links to both the warehouse the order is stored in and the invoice currently associated with this order.