ember-api-actions

Trigger "remote" actions on ember-data resources that don't fit into typical CRUD RESTful API design.

For example, if you have restful API endpoints like

GET     /fruits
POST    /fruits
GET     /fruits/123
PUT     /fruits/123
DELETE  /fruits/123

What happens if you want to consume API endpoints like these:

PUT    /fruits/123/ripen
GET    /fruits/citrus

Example Rails API routes:

config/routes.rb

Rails.application.routes.draw do

  resources :fruits do
    member do
      put 'ripen' to: 'fruits#ripen'
    end
    collection do
      get 'citrus' to: 'fruits#citrus_index'
    end
  end

end

This is not immediately intuitive with ember-data, and these kinds of API endpoints can be found in widely-used RESTful APIs. This library aims to make it easy.

Use

# ember-cli >= 0.2.3
ember install ember-api-actions

# ember-cli < 0.2.3
ember install:addon ember-api-actions

You can then add these "actions" (not to be confused with client-side ember.js actions) to your ember-data model

app/models/fruit.js

import DS from 'ember-data';
import { memberAction, collectionAction } from 'ember-api-actions';

const { attr } = DS;

export default DS.Model.extend({
  name: attr('string'),
  // /fruits/123/ripen
  ripen: memberAction({ path: 'ripen' }),
  // /fruits/citrus
  getAllCitrus: collectionAction({
    path: 'citrus',
    type: 'post', // HTTP POST request
    urlType: 'findRecord' // Base of the URL that's generated for the action
  })
});

you can then call these functions, and they will initiate API requests and return you the promise

// Pass data in, it will be sent in the POST or PUT request payload
myRecord.ripen({ someData: 'abc' }).then(response => {
  // do something when the API returns a response
});

Before and After Hooks

Use before and after hooks to customize the request and response. The hooks are available for both member actions and collection actions.

Before

Say you'd like to use ember-data to serialize your model, passing in only some, additional specific changes. You can do that like so:

eat: memberAction({
  path: 'eat',
  before(attributes) {
    let payload = this.serialize();
    payload.data.attributes = assign(payload.data.attributes, attributes);
    return payload;
  }
})

// Call it like this:
model.eat({ is_eaten: true });

// JSON API request payload would look something like:
{ data: { id: '1', type: 'fruit', attributes: { name: 'apple', is_eaten: true } } }

After

The after hook receives the response payload as an argument.

eat: memberAction({
 path: 'eat',
 after(response) {
   console.log(`Received response for model ${response.data.id}`);
 }
});

SerializeAndPush

You can use the after hook to push into the store. We've included a helper called serializeAndPush to do this.

import DS from 'ember-data';
import { memberAction, serializeAndPush } from 'ember-api-actions';

export default DS.Model.extend({
 eat: memberAction({
   path: 'eat',
   after: serializeAndPush
});

Warning this implemention only works for JSON API, but it should be easy to write your own after hook to handle your use case. Have a look at the implementation of serializeAndPush for an example.

Customization

ember-api-actions generates URLs and ajax configuration via ember-data adapters. It will identify the appropriate adapter, and call the buildURL and ajaxOptions methods to send a JSON request similar to way conventional ember-data usage works.

Customizing your adapter should customize requests sent out via this library, along with any other ember-data requests.

ember-api-actions uses the following methods on DS.Adapter

buildURL - for generating an action's URL
ajax (private) - to actually make the API request and return a promise

Compatibility

This addon is known to work with certain combinations of ember.js and ember-data

Ember.js	Ember-data
`1.10 <= ember < 1.13`	`1.0.0-beta.16.0 <= ember-data <= 1.0.0-beta.19`
`1.13.x`	`1.13.x`
`2.0.x`	`2.0.x`

Installation

git clone this repository
npm install
bower install

Running

ember serve
Visit your app at http://localhost:4200.

Running Tests

npm test (Runs ember try:testall to test your addon against multiple Ember versions)
ember test
ember test --server

Make sure to set ALLOW_DEPRECATIONS=true or the tests will raise errors on deprecation

Building

ember build

For more information on using ember-cli, visit http://ember-cli.com/.

Rxbsxn/ember-api-actions