Ember-data-link-traversal

An ember-data adapter and utility for link relation APIs. This adapter has no initial knowledge on resource URLs and gathers it by following from an api entrypoint.

The adapter is serializer independent and requires JSON API Links links (see "Compatibility" for more information).

Compatibility

ember-data-link-traversal supports ember data and ember data 1.13.4+. Currently it requires ember-data-hal-9000 because of the way it stores document links. By overwriting the ember-data-link-traversal/traversal extractRecordLinks method and let it return the record links, it should work with any other serializer but that isn't currently tested.

Usage

Install ember-data-link-traversal:

• npm install --save-dev ember-data-link-traversal
• Extend your application adapter from the Traversal adapter, e.g.:

// app/adapters/application.js
 
import TraversalAdapter from "ember-data-traversal-adapter/adapter";
export default TraversalAdapter.extend();

• Extend your application serializer from the HAL-9000 serializer, e.g.:

// app/serializers/application.js
 
import HalSerializer from "ember-data-traversal-adapter/serializer";
export default HalSerializer.extend();

Tested with Ember release, beta and canary channels.

Entrypoint

You need an ember model that represents your api entrypoint with all corresponding links. In the test app the entrypoint model is called root.

Link following

• import {follow} from 'ember-data-link-traversal/traversal'
• follow resolves a promise with a found record (like findRecord or findAll)
• start at your api entrypoint by using a links key string as the second method parameter

follow(store, 'user', 'family').then(familyRecord => {
 
});

• start from an already loaded record by using the record as the second parameter

follow(store, userRecord, 'family').then(familyRecord => {
 
});

• provide an object that is expanded in possible templated link uris
• the object will be expanded in each template uri link

// user._links = {pets: {href: '/foo{?onlyCats}', templated: true}}
follow(store, 'user', 'pets', {onlyCats: true}).then(petCatsCollection => {
 
});

Creating new records

• import {save} from 'ember-data-link-traversal/traversal'
• follows a given path to get a link to POST the locally created record

let newThread = store.createRecord('thread', {
  title: 'Big Brother'
});
 
// follow entrypoint, user, threads links and POST the new user json
save(store, 'user', 'threads', newThread).then(createdThread => {
 
});

Saving and deleting existing records

• uses ember data existing api

Pagination

• pagination in hal should done by following links on a collection response

{
  "_links": {
    "next": { "href": "api.tld/threads?page=2" },
    "self": { "href": "api.tld/threads{?page}" }
  },
  _embedded: […]
}

• the followUrl(store, modelClass, url, templateParams = {}) method allows you to load a given url

follow(store, user, 'threads').then(threads => 
  followUrl(store, threads.type, threads.get('meta.links.next')).then(nextPageThreads => {
      …
  })
})
 

Running Tests

• npm test # test all scenarios in config/ember-try.js
• ember try <scenario-name> test --server # test a specific scenario