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?
HAL and vnd.error
By Ian Littman
HAL and vnd.error
- 1,927