HAL and vnd.error

Ian Littman / @iansltx


Austin Homegrown API

Lightning Talks / October 2015


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)


  • 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!


eager-loaded related resources


  • 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


  • 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!


HAL and vnd.error

By Ian Littman

HAL and vnd.error

  • 1,453
Loading comments...

More from Ian Littman