An ember-data adapter for HAL-style APIs.
ember-data-hal-9000 supports ember data pre beta 19, beta 19, and ember data 1.13 support is coming soon.
|Ember Data < 1.0.0-beta.19||Ember Data 1.0.0-beta.19.2||Ember Data 1.13.8+, 2.0.0-beta.1+|
|use 0.1.x||use 0.2.x||use 0.3.x|
npm install --save-dev ember-data-hal-9000
- Extend your application adapter from the HAL-9000 adapter, e.g.:
- Extend your application serializer from the HAL-9000 serializer, e.g.:
Tested with Ember Data versions 1.13.4, 1.13.9, 2.0.0-beta.1 and 2.0.0-beta.2. Tested with Ember release, beta and canary channels.
HAL Links converted to JSONAPI links
HAL specifies that the API should return
_embedded values for
associations. The HAL serializer will restructure incoming JSON payloads
to turn these back into the format that ember-data expects for
sideloads. It will restructure arbitrarily deeply nested embeds, and it
_links keys when they match embedded properties. Example:
// GET /users/1id: 1name: 'the user'_links:self: href: '/users/1'pet: href: '/users/1/pet'_embedded:pet:id: 'pet-2'name: 'fido'// The HAL serializer will restructure this JSON like so:user:id: 1name: 'the user'pet: 'pet-2' // <-- adds the 'pet' property to user, using the pet id valuepets:id: 'pet-2'name: 'fido'links:self: '/users/1'// <-- note 'pet' link is deleted since the user's pet was embedded// This code in your route will work.store;
The HAL spec mentions that information about a collection resource can
be included in the root of the JSON payload, alongside the required
The HAL adapter will read all non-reserved property names (i.e., those other
_links) and set them as meta data. For example:
// Assuming GET /users returns this:_embedded:users: ... ...current_page: 1// Using this code in your route will work:store;
Note that this only works for collection resources. Singular resources, according to the HAL spec, have all their properties in the root of the payload so it is not possible to know which are intended to be meta data.
For this reason, if your API response includes a
meta key (for
singular or collection requests), the values in the meta will be set.
// Assuming GET /users/1 returns this:id: 1name: 'the user'meta:my_meta_val: true// Using this code in your route will work:store;
In addition, for collection resources only, the links will be set on the meta data as well. Example:
// Assuming GET /users returns this:_embedded: users: ... ..._links:self: '/users'next: '/users?page=2'// Using this code in your route will work:store;
Links for a singular resource will be available on the 'data' property, i.e.:
Note that when a singular resource response includes an embedded
resource, the HAL adapter will sideload that embedded resource and
delete the link for that resource, if there is one (otherwise
ember-data will eagerly follow the link when you
get the associated
resource). See the example above in the section on sideloading.
npm test# test all scenarios in config/ember-try.js
ember try <scenario-name> test --server# test a specific scenario