5. What is a Hypermedia API?
• Verb-oriented
• HATEOAS
• Client “drives” state changes taking actions
(aka following links) that the API provides
• JSON API is also a Hypermedia API
6. What is HAL?
• Optimized for developer on-boarding
• Built for machines, but human-friendly
15. HAL Example
{
count: 2,
_embedded: {
users: [{
id: 1,
name: 'Cory'
}, {
id: 2,
name: 'Bob'
}]
}
}
Users collection
Info about the resource
collection. (Metadata)
16. HAL Example
{
id: 1,
name: 'Cory',
_links: {
self: { href: '/' },
pets: { href: '/users/1/pets'}
}
}
Single User Resource _links
17. HAL Example
{
id: 1,
name: 'Cory',
_links: {
self: { href: '/' },
pets: { href: '/users/1/pets'}
}
}
Single User Resource _links
Follow this link to get my pets
18. The HAL Model
Resources and Links
• Resources have
• links to URIs
• embedded
resources
• state (aka data)
• Links have
• Target URI
• Relation
name (“self”,
“pets”, etc)
• (Some other
properties)
20. HAL vs JSON API
• HAL
• Serialization
spec (only)
• Minimal
• Arbitrary
nesting
• “Discoverable”
• JSON API
• Serialization
and upload
• Comprehensive
• “Side-loading” /
Flat structure
21. HAL and JSON API
• HAL
• Has links concept
• Is a Hypermedia API
• JSON API
• Has links concept
• Is a Hypermedia API
22. HAL vs Ember Data
• Ember Data Adapter
• builds URLs
• uses serializer to
generate request
payloads
• uses serializer to map
response payloads to
model instances
• Ember Data Serializer
• Normalizes payload into
objects that can be
`push`-ed to the store
• Extracts single/array,
`push`-ing results into
store
• Extracts metadata
23. HAL vs Ember Data
• ED’s store has its own expected JSON format
• ED will use links if they are in its expected format
• ED has ‘meta’ concept, HAL does not
24. ember-data-hal-9000
• No adapter (ironic)
• Serializer restructures payloads from
HAL style to ember-data’s expected
format
• Un-nests _embedded values into side
loads
• HAL has no formal metadata concept
• hal-9000 uses a heuristic to derive
metadata
26. ember-data-hal-9000
• Restructure and un-nest _embeddeds
• override `normalize` to rewrite “_links” ->
“links”
• override `extractSingle`, `extractArray` to
un-nest _embedded values, replacing with
ids and sideloading
27. ember-data-hal-9000
{
user: {
id: 1,
name: 'Cory',
pet: 2
},
pets: [{
id: 2,
name: 'Fido'
}]
}
{
id: 1,
name: 'Cory',
_embedded: {
pet: {
id: 2,
name: 'Fido'
}
}
}
HAL Format Store Format
28. ember-data-hal-9000
• HAL has no formal concept of metadata,
• but it has collection resource properties
• hal-9000 presumes these are metadata
Metadata
33. Cory Forsyth
@bantic
• Slides: http://bit.ly/ember-data-hal-slides
• ember-data-hal-9000 Ember Data Adapter
• Hypermedia APIS JavasScript Jabber
• HAL Discuss Google Group
• Designing Hypermedia APIs (Youtube)
• HAL Spec @ Stateless
• HAL Primer
• Interview with Mike Kelly
• HAL Explorer
• HAL Spec @ IETF
• aptible.com
Links
Photo credits
http://stateless.co/hal_specification.html