Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
HAL APIs and Ember
Data
Cory Forsyth
@bantic
201 Created
Matthew BealeCory Forsyth
http://201-created.com/
What is HAL?
• Created by Mike Kelly in 2011
• Hypertext Application Language
• API Response Format Specification
What is HAL?
Hypermedia API
What is a Hypermedia API?
• Verb-oriented
• HATEOAS
• Client “drives” state changes taking actions
(aka following links) t...
What is HAL?
• Optimized for developer on-boarding
• Built for machines, but human-friendly
HAL Example
{}
Simplest Possible Valid HAL Doc
HAL Example
GET /users/1
{
id: 1,
name: 'Cory'
}
Single resource
HAL Special Properties
• _embedded
• _links
• CURIEs
HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s)
HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s)
Links to related resources
HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s)
Links to related resources
Documentation “hints”
HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s) (optional)
Links to related resources (optional)
Do...
HAL Example
GET /users
{
_embedded: {
users: [{
id: 1,
name: 'Cory'
}, {
id: 2,
name: 'Bob'
}]
}
}
Users collection
HAL Example
{
count: 2,
_embedded: {
users: [{
id: 1,
name: 'Cory'
}, {
id: 2,
name: 'Bob'
}]
}
}
Users collection
Info ab...
HAL Example
{
id: 1,
name: 'Cory',
_links: {
self: { href: '/' },
pets: { href: '/users/1/pets'}
}
}
Single User Resource ...
HAL Example
{
id: 1,
name: 'Cory',
_links: {
self: { href: '/' },
pets: { href: '/users/1/pets'}
}
}
Single User Resource ...
The HAL Model
Resources and Links
• Resources have
• links to URIs
• embedded
resources
• state (aka data)
• Links have
• ...
The HAL Model
Resources and Links
HAL vs JSON API
• HAL
• Serialization
spec (only)
• Minimal
• Arbitrary
nesting
• “Discoverable”
• JSON API
• Serializatio...
HAL and JSON API
• HAL
• Has links concept
• Is a Hypermedia API
• JSON API
• Has links concept
• Is a Hypermedia API
HAL vs Ember Data
• Ember Data Adapter
• builds URLs
• uses serializer to
generate request
payloads
• uses serializer to m...
HAL vs Ember Data
• ED’s store has its own expected JSON format
• ED will use links if they are in its expected format
• E...
ember-data-hal-9000
• No adapter (ironic)
• Serializer restructures payloads from
HAL style to ember-data’s expected
forma...
ember-data-hal-9000
Thanks to Aptible (they are hiring)
ember-data-hal-9000
• Restructure and un-nest _embeddeds
• override `normalize` to rewrite “_links” ->
“links”
• override ...
ember-data-hal-9000
{
user: {
id: 1,
name: 'Cory',
pet: 2
},
pets: [{
id: 2,
name: 'Fido'
}]
}
{
id: 1,
name: 'Cory',
_emb...
ember-data-hal-9000
• HAL has no formal concept of metadata,
• but it has collection resource properties
• hal-9000 presum...
ember-data-hal-9000
{
total: 2,
_embedded: [{
users: [{
id: 1,
name: 'Cory'
}]
}]
}
HAL Format
ember-data-hal-9000
{
total: 2,
_embedded: [{
users: [{
id: 1,
name: 'Cory'
}]
}]
}
HAL Format
store.metadataFor(‘user’).t...
ember-data-hal-9000
{
id: 1,
name: 'Cory',
_links: {
pet: { href: '/users/1/pet' }
}
}
Link traversal
store.find('user', 1...
ember-data-hal-9000
{
id: 1,
name: 'Cory',
_links: {
pet: { href: '/users/1/pet' }
}
}
Link traversal
store.find('user', 1...
Cory Forsyth
@bantic
• Slides: http://bit.ly/ember-data-hal-slides
• ember-data-hal-9000 Ember Data Adapter
• Hypermedia A...
Upcoming SlideShare
Loading in …5
×

HAL APIs and Ember Data

2,432 views

Published on

Explains HAL Hypertext Application Language API response format and an Ember Data Adapter for it called ember-data-hal-9000.

Published in: Internet
  • Be the first to comment

HAL APIs and Ember Data

  1. 1. HAL APIs and Ember Data Cory Forsyth @bantic
  2. 2. 201 Created Matthew BealeCory Forsyth http://201-created.com/
  3. 3. What is HAL? • Created by Mike Kelly in 2011 • Hypertext Application Language • API Response Format Specification
  4. 4. What is HAL? Hypermedia API
  5. 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. 6. What is HAL? • Optimized for developer on-boarding • Built for machines, but human-friendly
  7. 7. HAL Example {} Simplest Possible Valid HAL Doc
  8. 8. HAL Example GET /users/1 { id: 1, name: 'Cory' } Single resource
  9. 9. HAL Special Properties • _embedded • _links • CURIEs
  10. 10. HAL Special Properties • _embedded • _links • CURIEs Embedded value(s)
  11. 11. HAL Special Properties • _embedded • _links • CURIEs Embedded value(s) Links to related resources
  12. 12. HAL Special Properties • _embedded • _links • CURIEs Embedded value(s) Links to related resources Documentation “hints”
  13. 13. HAL Special Properties • _embedded • _links • CURIEs Embedded value(s) (optional) Links to related resources (optional) Documentation “hints” (optional)
  14. 14. HAL Example GET /users { _embedded: { users: [{ id: 1, name: 'Cory' }, { id: 2, name: 'Bob' }] } } Users collection
  15. 15. HAL Example { count: 2, _embedded: { users: [{ id: 1, name: 'Cory' }, { id: 2, name: 'Bob' }] } } Users collection Info about the resource collection. (Metadata)
  16. 16. HAL Example { id: 1, name: 'Cory', _links: { self: { href: '/' }, pets: { href: '/users/1/pets'} } } Single User Resource _links
  17. 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. 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)
  19. 19. The HAL Model Resources and Links
  20. 20. HAL vs JSON API • HAL • Serialization spec (only) • Minimal • Arbitrary nesting • “Discoverable” • JSON API • Serialization and upload • Comprehensive • “Side-loading” / Flat structure
  21. 21. HAL and JSON API • HAL • Has links concept • Is a Hypermedia API • JSON API • Has links concept • Is a Hypermedia API
  22. 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. 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. 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
  25. 25. ember-data-hal-9000 Thanks to Aptible (they are hiring)
  26. 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. 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. 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
  29. 29. ember-data-hal-9000 { total: 2, _embedded: [{ users: [{ id: 1, name: 'Cory' }] }] } HAL Format
  30. 30. ember-data-hal-9000 { total: 2, _embedded: [{ users: [{ id: 1, name: 'Cory' }] }] } HAL Format store.metadataFor(‘user’).total
  31. 31. ember-data-hal-9000 { id: 1, name: 'Cory', _links: { pet: { href: '/users/1/pet' } } } Link traversal store.find('user', 1).then(function(user){ return user.get('pet'); });
  32. 32. ember-data-hal-9000 { id: 1, name: 'Cory', _links: { pet: { href: '/users/1/pet' } } } Link traversal store.find('user', 1).then(function(user){ return user.get('pet'); }); fetches /users/1/pet
  33. 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

×