Ember and Rails 5 with JSON API: A Modern Bridge

The JSON API specification dovetails nicely with the Ember and Rails philosophy of convention over configuration.

The plan here is to put it to work. We’ll build a full-blown Ember app hooked to a Rails 5 API using JSON API, step by step.

The app

We will create a simple bookstore.

Authors write books. They are published by either a publishing house or the author himself (self-published).

The bookstore sells books and makes money on discounts offered by publishers. Authors who self-publish offer a fixed discount of 10%.

Setting it up

Rails 5 API-only

Make sure you are running Ruby 2.2.2 or newer: that is what Rails 5 requires. Let’s install it.

$ ruby -v
ruby 2.2.2p95 (2015-04-13 revision 50295) [x86_64-darwin14]
$ bundler -v
Bundler version 1.10.6

$ gem install rails --pre --no-ri --no-rdoc
# ...
Successfully installed rails-5.0.0
12 gems installed

Note down the Rails version (5.0.0 in our case). It’s possible we have multiple gems if Rails was previously installed in our system. We will create our backend API project ensuring it’s Rails 5:

$ rails _5.0.0_ new bookstore-api --api

Ember client app

Let’s pick a name and create our shiny new Ember app.

$ ember new bookstore

Generating models

Now that we have both apps ready, it’s time to define and generate our models.

• Book attributes: title:string, price:decimal, author:belongs-to, publisher:belongs-to(polymorphic)

• PublishingHouse attributes: name:string, discount:decimal, published-books:has-many

• Author attributes: name:string, books:has-many, published-books:has-many

• Publisher is the polymorphic type of PublishingHouse and Author

Rails

Using the Rails generator we’ll scaffold required files and migrate the database to those changes. Inside the Rails project directory:

$ bin/rails generate scaffold book title 'price:decimal{5,2}' author:references publisher:references{polymorphic}
$ bin/rails g scaffold author name
$ bin/rails g scaffold publishing_house name 'discount:decimal{2,2}'

$ bin/rails db:migrate

All this is fancy but we have no data to interact with…

Sample data can be provided in the db/seeds.rb file.

# db/seeds.rb

pub1 = PublishingHouse.create(name: "ABC Publisher", discount: 40)
pub2 = PublishingHouse.create(name: "Acme Publishing House", discount: 50)
pub3 = PublishingHouse.create(name: "Foobar Corporation", discount: 55)

author1 = Author.create(name: "James Jackson")
author2 = Author.create(name: "Roberta Rock")
author3 = Author.create(name: "Daniel Duck")
author4 = Author.create(name: "Amanda Djidjinski")
author5 = Author.create(name: "Zoe Zack")
author6 = Author.create(name: "Bill Burray")
author7 = Author.create(name: "Charlie Chuck")

book1 = Book.create(title: "The Great Escape", author: author7, publisher: pub1, price: 24.20)
book2 = Book.create(title: "Saving Myself", author: author6, publisher: pub1, price: 14.13)
book3 = Book.create(title: "The Killer Doctors", author: author5, publisher: pub1, price: 15.12)
book4 = Book.create(title: "Marianne", author: author4, publisher: pub1, price: 10.50)
book5 = Book.create(title: "On the Verge of Salvation", author: author4, publisher: pub2, price: 11.76)
book6 = Book.create(title: "Fields of L", author: author3, publisher: pub2, price: 27.87)
book7 = Book.create(title: "Waterfront", author: author2, publisher: pub2, price: 11.97)
book8 = Book.create(title: "Bored as Hell", author: author6, publisher: pub3, price: 10.96)
book9 = Book.create(title: "History of the Silk Road", author: author7, publisher: pub3, price: 8.10)
booka = Book.create(title: "Something for Later", author: author1, publisher: author1, price: 9.54)
bookb = Book.create(title: "What If", author: author3, publisher: author3, price: 13.32)
bookc = Book.create(title: "Lilly Reborn", author: author4, publisher: pub3, price: 16.43)
bookd = Book.create(title: "Anathema", author: author5, publisher: author5, price: 9.41)
booke = Book.create(title: "Best Of", author: author2, publisher: pub3, price: 12.24)
bookf = Book.create(title: "Anyway", author: author6, publisher: pub3, price: 19.99)

Run the command to seed the database.

$ bin/rails db:seed

We should be set!

Enable JSON API and start server

Before we boot we need to include active_model_serializers:

$ echo 'gem "active_model_serializers", "~> 0.10.2"' >> Gemfile
$ bundle

And configure Rails for JSON API serialization.

1. Create an initializer at config/initializers/json_api.rb with the following code:

   require 'active_model_serializers/register_jsonapi_renderer'
   
   ActiveModelSerializers.config.adapter = :json_api
   

2. Generate appropriate serializers for each class:

   $ bin/rails g serializer book
   $ bin/rails g serializer author
   $ bin/rails g serializer publishing_house
   

Run the server and try to fetch data with curl:

$ bin/rails server --binding 0.0.0.0
=> Booting Puma
=> Rails 5.0.0.beta3 application starting in development on http://0.0.0.0:3000

# in another tab/window
$ curl http://localhost:3000/publishing_houses

# if you want pretty printing (and have python or jq installed)
$ curl -s http://localhost:3000/publishing_houses | python -m json.tool
$ curl -s http://localhost:3000/publishing_houses | jq '.'

The server should respond something like:

{
  "data": [
    {
      "id": "1",
      "type": "publishing_houses"
    },
    {
      "id": "2",
      "type": "publishing_houses"
    },
    {
      "id": "3",
      "type": "publishing_houses"
    }
  ]
}

Success? I hope! No other attributes than id are present for now. We will add them in a minute.

Ember

Generate models with Ember CLI:

$ ember generate resource books title:string price:number author:belongs-to publisher:belongs-to
$ ember g resource authors name:string books:has-many
$ ember g resource publishing-houses name:string discount:number books:has-many

(Polymorphic) Relationships!

Reviewing our model specs we notice that an author can have many books and that he can publish. Publishing houses also have a bunch of published books.

We must ensure our models and serializers are set up correctly. For your convenience, I highlighted the modified lines.

Rails

Book model

Nothing to change here. Note that publisher is not a model but a polymorphic interface.

# app/models/book.rb

class Book < ApplicationRecord
 belongs_to :author
 belongs_to :publisher, polymorphic: true
end

BookSerializer

Include author and publisher ids (and type!) in the output.

# app/serializers/book_serializer.rb

class BookSerializer < ActiveModel::Serializer
 attributes :id, :title, :price
 belongs_to :author
 belongs_to :publisher
end

Author model

Authors that behave as publishers offer a fixed 10% discount. There is no field in the database: we will return a constant.

Here we have to add two has_many :books statements. First one because an author authors books. And the second one because he can publish books. As both are book collections, we will alter the name of the published items and call it published. Rails can’t infere those relationship details so we need to tell it where the table and foreign key are located.

The published books are published by a publisher (our polymorphic interface). We associate it using the as keyword.

# app/models/author.rb

class Author < ApplicationRecord
 def discount() 10 end
 has_many :books
 has_many :published, foreign_key: :publisher_id, class_name: 'Book', as: :publisher
end

AuthorSerializer

Ask the serializer to include authored and published books’ ids. Additionally, add the :discount property.

# app/serializers/author_serializer.rb

class AuthorSerializer < ActiveModel::Serializer
  attributes :id, :name, :discount
  has_many :books
  has_many :published
end

PublishingHouse model

In Author we changed :books to :published. Likewise, we need to make that change to PublishingHouse.

# app/models/publishing_house.rb

class PublishingHouse < ApplicationRecord
  has_many :published, as: :publisher, foreign_key: :publisher_id, class_name: 'Book'
end

PublishingHouseSerializer

We simply add the aforementioned published property in order to get those published book ids in our JSON.

# app/serializers/publishing_house_serializer.rb

class PublishingHouseSerializer < ActiveModel::Serializer
  attributes :id, :name, :discount
  has_many :published
end

Ember

An abstract Publisher is necessary to model the polymorphic relationship in Ember.

$ ember g model publisher

Publisher model

Once created, we add all common properties to publishers: name, discount, published.

// app/models/publisher.js

import Model from 'ember-data/model';
import attr from 'ember-data/attr';
import { hasMany } from 'ember-data/relationships';

export default Model.extend({
  name: attr('string'),
  discount: attr('number'),
  published: hasMany('book', { async: true })
});

(A note about async: true: it indicates the relationship should be loaded asynchronously.)

PublishingHouse model

Not much here. PublishingHouse simply extends Publisher.

// app/models/publishing-house.js

import Publisher from './publisher';

export default Publisher.extend();

We need to create what is called an Adapter.

$ ember generate adapter application
installing adapter
  create app/adapters/application.js
installing adapter-test
  create tests/unit/adapters/application-test.js

In it, we will override a function called pathForType that will underscore (and pluralize) the type:

// app/adapters/application.js

import JSONAPIAdapter from 'ember-data/adapters/json-api';
import Ember from 'ember';

export default JSONAPIAdapter.extend({

  pathForType: function(type) {
    return Ember.String.pluralize(Ember.String.underscore(type));
  }

});

Author model

Author extends Publisher, too. The difference with PublishingHouse, is that an author has a collection of authored books.

// app/models/author.js

import Publisher from './publisher';
import { hasMany } from 'ember-data/relationships';

export default Publisher.extend({
  books: hasMany('book', { async: true })
});

Book model

The code below explains itself. We have two belongsTo relationships (one to the author, the other to a publisher, polymorphic) which we want async.

// app/models/book.js

import DS from 'ember-data';

export default DS.Model.extend({
  title: DS.attr('string'),
  price: DS.attr('number'),
  author: DS.belongsTo('author', { async: true, inverse: 'books' }),
  publisher: DS.belongsTo('publisher', { polymorphic: true, async: true, inverse: 'published' })
});

What is inverse you may ask? Turns out that Author has two book collections: books (authored) and published. Inverse is how Ember Data deals with these ambiguities.

Well, that was a lot! (But we learned a lot, too.) Let’s get ready to explore our data from the client.

Exploring data with the Inspector

If you still don’t have Ember Inspector go ahead now and grab it.

Let’s boot Ember CLI server. We are going to use the --proxy flag to let it know our backend is listening at port 3000.

$ ember server --proxy http://localhost:3000
Proxying to http://localhost:3000
Livereload server on http://localhost:49152
Serving on http://localhost:4200/

Navigate to http://localhost:4200 and open Developer Tools. Go to Ember and click on the Data tab. Leave an active console, too.

Get hold of the application route through the Inspector’s $E special variable (here’s how). We are particularly interested in accessing its reference to the store.

Loadin’ stuff

$E.store.findAll('book');

Great - now we have all books loaded in our local store.

Time to play around with peekAll, peekRecord, and so on. Try promises on relationships. For example:

$E.store.peekAll('book').objectAt(6).get('author').then(function(data) { alert(data.get('name')) })

$E.store.peekRecord('author', 2).get('books').map(function(value) { return value.get('title') })

Once you’re ready, let’s carry on by cleaning up the store:

$E.store.unloadAll()

Saving a new record

In order to save a new book, we will have to configure our controllers to deserialize the incoming parameters – turn them from JSON API into a standard Ruby hash. In this example, our BooksController:

# app/controllers/books_controller.rb

# ...

def book_params
  res = ActiveModelSerializers::Deserialization.jsonapi_parse(params, polymorphic: [:publisher])
  res[:publisher_type] = res[:publisher_type].singularize.capitalize
  res
end

$ ember generate serializer application
installing serializer
  create app/serializers/application.js
installing serializer-test
  create tests/unit/serializers/application-test.js

// app/serializers/application.js

export default DS.JSONAPISerializer.extend({
  payloadKeyFromModelName(modelName) {
    return Ember.String.singularize(Ember.String.capitalize(modelName));
  }
});

Author James Jackson just self-published a new book called “Ember and Coal”. Let’s store it in our system.

We know James is author with id 1. In order to find him we will use findRecord which returns a Promise.

var james;
$E.store.findRecord('author', 1).then(function(author) {
 james = author;
});

Alternatively, we could have retrieved James synchronously if we knew he was loaded in the local store. That is what peekRecord is for.

const james = $E.store.peekRecord('author', 1);

Either way, we can use the james object to create his new book. Remember that publisher is polymorphic and will accept a PublishingHouse or an Author. In this case James is publishing his own book, so that will be an Author.

const book = $E.store.createRecord('book', { title: "Ember and Coal", price: 9.99, author: james, publisher: james});
book.save()

Awesome.

Calling james.get('books') will get us all of his books (2 in total).

Last requirement

Our UX team has asked us to display the (soon to come) author page as fast as possible.

We decided that whenever we load an author, it will bring all its books with it – in the same request. In authors_controller.rb we’ll define:

# app/controllers/authors_controller.rb

# GET /authors/1
def show
 render json: @author, include: ['books']
end

Let’s reload the browser and then run in the console:

$E.store.findRecord('author', 4)

We should see the requested author Amanda Djidjinski along with her three books.

(Check the Network panel, only one request was fired!)

I created repositories for both the Bookstore client and the Bookstore API on Github.

Moving forward

In our next instalment, we’ll use this data skeleton to work on routes and controllers for the Bookstore. We’ll learn to deal with metadata, errors, background fetches, caching via shouldReloadRecord, query pameters and much more.

Were you able to make your app run fine? Any questions or problems along the way? Let me know in the comments!