jmurphyau / ember-api-actions

Trigger API actions in ember.js apps

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

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

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

Installation

• git clone this repository
• npm install
• bower install

Running

• ember server
• Visit your app at http://localhost:4200.

Running Tests

• ember test
• ember test --server

Building

• ember build

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