HAL and vnd.error
Ian Littman / @iansltx
Austin Homegrown API
Lightning Talks / October 2015
http://ian.im/lthal15
Nope, not that hal
Hypertext application language
A (
proposed
) standard for denoting hypermedia API relationships in a quick, light, consistent way
Like JSON Collection or Siren
application/hal+(json|xml)
Two components
_links
_embedded
(your plain old content goes here)
_links
Attributes (all but href optional)
href: /users/bob or /users/{name}
title: Bob
templated: true/false
Indexed by relationship
e.g. prev, next, contactInfo
use array syntax for multiple links
Curies!
_embedded
eager-loaded related resources
curies
Link relationships can be prefixed by {curie name}:
Links based on the concept of the relationship itself
Under "curies" property; they have the same properties a normal link has, plus "name"
Let's take a look
vnd.error
A HAL-compatible
way
of displaying HTTP API errors
Like HTTP problem
application/vnd.error
One required component: message (human readable)
Multiple errors?
Use _embedded.errors
Use a "total" property
Other fields
logref - instance ID of the error (or the request)
path - JSON pointer to the resource the error is about
_links
help - an HTML document describing the error
describes - another server side representation of the error
about - the resource that the error is about
that's it!
questions?