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

1. HAL APIs and Ember
Data
Cory Forsyth
@bantic

2. 201 Created
Matthew BealeCory Forsyth
http://201-created.com/

3. What is HAL?
• Created by Mike Kelly in 2011
• Hypertext Application Language
• API Response Format Specification

4. What is HAL?
Hypermedia API

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

7. HAL Example
{}
Simplest Possible Valid HAL Doc

8. HAL Example
GET /users/1
{
id: 1,
name: 'Cory'
}
Single resource

9. HAL Special Properties
• _embedded
• _links
• CURIEs

10. HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s)

11. HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s)
Links to related resources

12. HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s)
Links to related resources
Documentation “hints”

13. HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s) (optional)
Links to related resources (optional)
Documentation “hints” (optional)

14. HAL Example
GET /users
{
_embedded: {
users: [{
id: 1,
name: 'Cory'
}, {
id: 2,
name: 'Bob'
}]
}
}
Users collection

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)

19. The HAL Model
Resources and Links

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

25. ember-data-hal-9000
Thanks to Aptible (they are hiring)

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

29. ember-data-hal-9000
{
total: 2,
_embedded: [{
users: [{
id: 1,
name: 'Cory'
}]
}]
}
HAL Format

30. ember-data-hal-9000
{
total: 2,
_embedded: [{
users: [{
id: 1,
name: 'Cory'
}]
}]
}
HAL Format
store.metadataFor(‘user’).total

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. 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. 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