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) that the API provides

• JSON API is also a Hypermedia API

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)

Documentation “hints” (optional)

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 about the resource collection. (Metadata)

HAL Example

{id: 1,name: 'Cory',_links: {self: { href: '/' },pets: { href: '/users/1/pets'}

}}

Single User Resource _links

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

The HAL ModelResources and Links

• Resources have

• links to URIs

• embedded resources

• state (aka data)

• Links have

• Target URI

• Relation name (“self”, “pets”, etc)

• (Some other properties)

The HAL ModelResources and Links

HAL vs JSON API• HAL

• Serialization spec (only)

• Minimal

• Arbitrary nesting

• “Discoverable”

• JSON API

• Serialization and upload

• Comprehensive

• “Side-loading” / Flat structure

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

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

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

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 `extractSingle`, `extractArray` to un-nest _embedded values, replacing with ids and sideloading

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

ember-data-hal-9000

• HAL has no formal concept of metadata,

• but it has collection resource properties

• hal-9000 presumes these are metadata

Metadata

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’).total

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');

});

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

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