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,926