HAL APIs and Ember Data
-
Upload
cory-forsyth -
Category
Internet
-
view
578 -
download
1
Transcript of HAL APIs and Ember Data
![Page 1: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/1.jpg)
HAL APIs and Ember Data
Cory Forsyth @bantic
![Page 3: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/3.jpg)
What is HAL?
• Created by Mike Kelly in 2011
• Hypertext Application Language
• API Response Format Specification
![Page 4: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/4.jpg)
What is HAL?
Hypermedia API
![Page 5: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/5.jpg)
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
![Page 6: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/6.jpg)
What is HAL?
• Optimized for developer on-boarding
• Built for machines, but human-friendly
![Page 7: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/7.jpg)
HAL Example
{}
Simplest Possible Valid HAL Doc
![Page 8: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/8.jpg)
HAL Example
GET /users/1
{id: 1,name: 'Cory'
}
Single resource
![Page 9: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/9.jpg)
HAL Special Properties
• _embedded
• _links
• CURIEs
![Page 10: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/10.jpg)
HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s)
![Page 11: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/11.jpg)
HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s)
Links to related resources
![Page 12: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/12.jpg)
HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s)
Links to related resources
Documentation “hints”
![Page 13: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/13.jpg)
HAL Special Properties
• _embedded
• _links
• CURIEs
Embedded value(s) (optional)
Links to related resources (optional)
Documentation “hints” (optional)
![Page 14: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/14.jpg)
HAL Example
GET /users
{_embedded: {
users: [{id: 1,name: 'Cory'
}, {id: 2,name: 'Bob'
}]}
}
Users collection
![Page 15: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/15.jpg)
HAL Example
{count: 2,_embedded: {
users: [{id: 1,name: 'Cory'
}, {id: 2,name: 'Bob'
}]}
}
Users collection
Info about the resource collection. (Metadata)
![Page 16: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/16.jpg)
HAL Example
{id: 1,name: 'Cory',_links: {self: { href: '/' },pets: { href: '/users/1/pets'}
}}
Single User Resource _links
![Page 17: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/17.jpg)
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
![Page 18: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/18.jpg)
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)
![Page 19: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/19.jpg)
The HAL ModelResources and Links
![Page 20: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/20.jpg)
HAL vs JSON API• HAL
• Serialization spec (only)
• Minimal
• Arbitrary nesting
• “Discoverable”
• JSON API
• Serialization and upload
• Comprehensive
• “Side-loading” / Flat structure
![Page 21: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/21.jpg)
HAL and JSON API
• HAL
• Has links concept
• Is a Hypermedia API
• JSON API
• Has links concept
• Is a Hypermedia API
![Page 22: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/22.jpg)
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
![Page 23: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/23.jpg)
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
![Page 24: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/24.jpg)
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
![Page 25: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/25.jpg)
ember-data-hal-9000
Thanks to Aptible (they are hiring)
![Page 26: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/26.jpg)
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
![Page 27: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/27.jpg)
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
![Page 28: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/28.jpg)
ember-data-hal-9000
• HAL has no formal concept of metadata,
• but it has collection resource properties
• hal-9000 presumes these are metadata
Metadata
![Page 29: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/29.jpg)
ember-data-hal-9000
{total: 2,_embedded: [{users: [{id: 1,name: 'Cory'
}]}]
}
HAL Format
![Page 30: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/30.jpg)
ember-data-hal-9000
{total: 2,_embedded: [{users: [{id: 1,name: 'Cory'
}]}]
}
HAL Format
store.metadataFor(‘user’).total
![Page 31: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/31.jpg)
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');
});
![Page 32: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/32.jpg)
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
![Page 33: HAL APIs and Ember Data](https://reader038.fdocuments.in/reader038/viewer/2022103018/55a6a3d41a28ab9a148b45d0/html5/thumbnails/33.jpg)
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