BT

New Early adopter or innovator? InfoQ has been working on some new features for you. Learn more

Amazon Chooses HAL Media Type for AppStream API

| by Steve Klabnik Follow 0 Followers on Mar 03, 2014. Estimated reading time: 2 minutes |

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.

Rate this Article

Adoption Stage
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread
Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Discuss

Login to InfoQ to interact with what matters most to you.


Recover your password...

Follow

Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.

Like

More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.

Notifications

Stay up-to-date

Set up your notifications and don't miss out on content that matters to you

BT