Leanpub: Publish Early, Publish Often

Models

Introduction

Models

In Ember, every route has an associated model. This model is set by implementing a route’s model hook, by passing the model as an argument to {{link-to}}, or by calling a route’s transitionTo() method.

See Specifying a Route’s Model for more information on setting a route’s model.

For simple applications, you can get by using jQuery to load JSON data from a server, then use those JSON objects as models.

However, using a model library that manages finding models, making changes, and saving them back to the server can dramatically simplify your code while improving the robustness and performance of your application.

Many Ember apps use Ember Data to handle this. Ember Data is a library that integrates tightly with Ember.js to make it easy to retrieve records from a server, cache them for performance, save updates back to the server, and create new records on the client.

Without any configuration, Ember Data can load and save records and their relationships served via a RESTful JSON API, provided it follows certain conventions.

If you need to integrate your Ember.js app with existing JSON APIs that do not follow strong conventions, Ember Data is designed to be easily configurable to work with whatever data your server returns.

Ember Data is also designed to work with streaming APIs like socket.io, Firebase, or WebSockets. You can open a socket to your server and push changes to records into the store whenever they occur.

Currently, Ember Data ships as a separate library from Ember.js. Until Ember Data is included as part of the standard distribution, you can get a copy of the latest passing build from emberjs.com/builds:

Core Concepts

Learning to use Ember Data is easiest once you understand some of the concepts that underpin its design.

Store

The store is the central repository of records in your application. You can think of the store as a cache of all of the records available in your app. Both your application’s controllers and routes have access to this shared store; when they need to display or modify a record, they will first ask the store for it.

This instance of DS.Store is created for you automatically and is shared among all of the objects in your application.

You will use the store to retrieve records, as well to create new ones. For example, we might want to find an App.Person model with the ID of 1 from our route’s model hook:

App.IndexRoute = Ember.Route.extend({
 model: function() {
   return this.store.find('person', 1);
 }
});

Models

A model is a class that defines the properties and behavior of the data that you present to the user. Anything that the user expects to see if they leave your app and come back later (or if they refresh the page) should be represented by a model.

For example, if you were writing a web application for placing orders at a restaurant, you might have models like Order, LineItem, and MenuItem.

Fetching orders becomes very easy:

1 this.store.find('order');

Models define the type of data that will be provided by your server. For example, a Person model might have a firstName attribute that is a string, and a birthday attribute that is a date:

App.Person = DS.Model.extend({
 firstName: DS.attr('string'),
 birthday:  DS.attr('date')
});

A model also describes its relationships with other objects. For example, an Order may have many LineItems, and a LineItem may belong to a particular Order.

App.Order = DS.Model.extend({
 lineItems: DS.hasMany('lineItem')
});

App.LineItem = DS.Model.extend({
 order: DS.belongsTo('order')
});

Models don’t have any data themselves; they just define the properties and behavior of specific instances, which are called records.

Records

A record is an instance of a model that contains data loaded from a server. Your application can also create new records and save them back to the server.

A record is uniquely identified by its model type and id.

For example, if you were writing a contact management app, you might have a model called Person. An individual record in your app might have a type of Person and an ID of 1 or steve-buscemi.

1 this.store.find('person', 1); // => { id: 1, name: 'steve-buscemi' }

IDs are usually assigned by the server when you save them for the first time, but you can also generate IDs client-side.

Adapter

An adapter is an object that knows about your particular server backend and is responsible for translating requests for and changes to records into the appropriate calls to your server.

For example, if your application asks for a person record with an ID of 1, how should Ember Data load it? Is it over HTTP or a WebSocket? If it’s HTTP, is the URL /person/1 or /resources/people/1?

The adapter is responsible for answering all of these questions. Whenever your app asks the store for a record that it doesn’t have cached, it will ask the adapter for it. If you change a record and save it, the store will hand the record to the adapter to send the appropriate data to your server and confirm that the save was successful.

Serializer

A serializer is responsible for turning a raw JSON payload returned from your server into a record object.

JSON APIs may represent attributes and relationships in many different ways. For example, some attribute names may be camelCased and others may be under_scored. Representing relationships is even more diverse: they may be encoded as an array of IDs, an array of embedded objects, or as foreign keys.

When the adapter gets a payload back for a particular record, it will give that payload to the serializer to normalize into the form that Ember Data is expecting.

While most people will use a serializer for normalizing JSON, because Ember Data treats these payloads as opaque objects, there’s no reason they couldn’t be binary data stored in a Blob or ArrayBuffer.

Automatic Caching

The store will automatically cache records for you. If a record had already been loaded, asking for it a second time will always return the same object instance. This minimizes the number of round-trips to the server, and allows your application to render its UI to the user as fast as possible.

For example, the first time your application asks the store for a person record with an ID of 1, it will fetch that information from your server.

However, the next time your app asks for a person with ID 1, the store will notice that it had already retrieved and cached that information from the server. Instead of sending another request for the same information, it will give your application the same record it had provided it the first time. This feature—always returning the same record object, no matter how many times you look it up—is sometimes called an identity map.

Using an identity map is important because it ensures that changes you make in one part of your UI are propagated to other parts of the UI. It also means that you don’t have to manually keep records in sync—you can ask for a record by ID and not have to worry about whether other parts of your application have already asked for and loaded it.

Architecture Overview

The first time your application asks the store for a record, the store sees that it doesn’t have a local copy and requests it from your adapter. Your adapter will go and retrieve the record from your persistence layer; typically, this will be a JSON representation of the record served from an HTTP server.

Diagram showing process for finding an unloaded record

As illustrated in the diagram above, the adapter cannot always return the requested record immediately. In this case, the adapter must make an asynchronous request to the server, and only when that request finishes loading can the record be created with its backing data.

Because of this asynchronicity, the store immediately returns a promise from the find() method. Similarly, any requests that the store makes to the adapter also return promises.

Once the request to the server returns with a JSON payload for the requested record, the adapter resolves the promise it returned to the store with the JSON.

The store then takes that JSON, initializes the record with the JSON data, and resolves the promise returned to your application with the newly-loaded record.

Diagram showing process for finding an unloaded record after the payload has returned from the server

Let’s look at what happens if you request a record that the store already has in its cache.

Diagram showing process for finding an unloaded record after the payload has returned from the server

In this case, because the store already knew about the record, it returns a promise that it resolves with the record immediately. It does not need to ask the adapter (and, therefore, the server) for a copy since it already has it saved locally.

These are the core concepts you should understand to get the most out of Ember Data. The following sections go into more depth about each of these concepts, and how to use them together.

Defining Models

A model is a class that defines the properties and behavior of the data that you present to the user. Anything that the user expects to see if they leave your app and come back later (or if they refresh the page) should be represented by a model.

Make sure to include ember-data.js after ember.js

1 <script type="text/javascript" src="ember.js"></script>
2 <script type="text/javascript" src="ember-data.js"></script>

For every model in your application, create a subclass of DS.Model:

1 App.Person = DS.Model.extend();

After you have defined a model class, you can start finding and creating records of that type. When interacting with the store, you will need to specify a record’s type using the model name. For example, the store’s find() method expects a string as the first argument to tell it what type of record to find:

1 store.find('person', 1);

The table below shows how model names map to model classes.

Defining Attributes

You can specify which attributes a model has by using DS.attr.

var attr = DS.attr;

App.Person = DS.Model.extend({
 firstName: attr(),
 lastName: attr(),
 birthday: attr()
});

Attributes are used when turning the JSON payload returned from your server into a record, and when serializing a record to save back to the server after it has been modified.

You can use attributes just like any other property, including as part of a computed property. Frequently, you will want to define computed properties that combine or transform primitive attributes.

var attr = DS.attr;

App.Person = DS.Model.extend({
 firstName: attr(),
 lastName: attr(),

 fullName: function() {
   return this.get('firstName') + ' ' + this.get('lastName');
 }.property('firstName', 'lastName')
});

For more about adding computed properties to your classes, see Computed Properties.

If you don’t specify the type of the attribute, it will be whatever was provided by the server. You can make sure that an attribute is always coerced into a particular type by passing a type to attr:

App.Person = DS.Model.extend({
 birthday: DS.attr('date')
});

The default adapter supports attribute types of string, number, boolean, and date. Custom adapters may offer additional attribute types, and new types can be registered as transforms. See the documentation section on the REST Adapter.

Please note: Ember Data serializes and deserializes dates according to ISO 8601. For example: 2014-05-27T12:54:01

Options

DS.attr takes an optional hash as a second parameter:

defaultValue: Pass a string or a function to be called to set the attribute to a default value if none is supplied.

Example

var attr = DS.attr;

App.User = DS.Model.extend({
   username: attr('string'),
   email: attr('string'),
   verified: attr('boolean', {defaultValue: false}),
   createdAt: DS.attr('string', {
       defaultValue: function() { return new Date(); }
   })
});

Defining Relationships

Ember Data includes several built-in relationship types to help you define how your models relate to each other.

One-to-One

To declare a one-to-one relationship between two models, use DS.belongsTo:

App.User = DS.Model.extend({
 profile: DS.belongsTo('profile')
});

App.Profile = DS.Model.extend({
 user: DS.belongsTo('user')
});

One-to-Many

To declare a one-to-many relationship between two models, use DS.belongsTo in combination with DS.hasMany, like this:

App.Post = DS.Model.extend({
 comments: DS.hasMany('comment')
});

App.Comment = DS.Model.extend({
 post: DS.belongsTo('post')
});

Many-to-Many

To declare a many-to-many relationship between two models, use DS.hasMany:

App.Post = DS.Model.extend({
 tags: DS.hasMany('tag')
});

App.Tag = DS.Model.extend({
 posts: DS.hasMany('post')
});

Explicit Inverses

Ember Data will do its best to discover which relationships map to one another. In the one-to-many code above, for example, Ember Data can figure out that changing the comments relationship should update the post relationship on the inverse because post is the only relationship to that model.

However, sometimes you may have multiple belongsTo/hasManys for the same type. You can specify which property on the related model is the inverse using DS.hasMany’s inverse option:

var belongsTo = DS.belongsTo,
   hasMany = DS.hasMany;

App.Comment = DS.Model.extend({
 onePost: belongsTo('post'),
 twoPost: belongsTo('post'),
 redPost: belongsTo('post'),
 bluePost: belongsTo('post')
});


App.Post = DS.Model.extend({
 comments: hasMany('comment', {
   inverse: 'redPost'
 })
});

You can also specify an inverse on a belongsTo, which works how you’d expect.

Reflexive relation

When you want to define a reflexive relation, you must either explicitly define the other side, and set the explicit inverse accordingly, and if you don’t need the other side, set the inverse to null.

var belongsTo = DS.belongsTo,
   hasMany = DS.hasMany;

App.Folder = DS.Model.extend({
 children: hasMany('folder', {inverse: 'parent'}),
 parent: belongsTo('folder', {inverse: 'children'})
});

var belongsTo = DS.belongsTo,

App.Folder = DS.Model.extend({
 parent: belongsTo('folder', {inverse: null})
});

Creating Deleting Records

You can create records by calling the createRecord method on the store.

store.createRecord('post', {
 title: 'Rails is Omakase',
 body: 'Lorem ipsum'
});

The store object is available in controllers and routes using this.store.

Although createRecord is fairly straightforward, the only thing to watch out for is that you cannot assign a promise as a relationship, currently.

For example, if you want to set the author property of a post, this would not work if the user with id isn’t already loaded into the store:

var store = this.store;

store.createRecord('post', {
 title: 'Rails is Omakase',
 body: 'Lorem ipsum',
 author: store.find('user', 1)
});

However, you can easily set the relationship after the promise has fulfilled:

var store = this.store;

var post = store.createRecord('post', {
 title: 'Rails is Omakase',
 body: 'Lorem ipsum'
});

store.find('user', 1).then(function(user) {
 post.set('author', user);
});

Deleting Records

Deleting records is just as straightforward as creating records. Just call deleteRecord() on any instance of DS.Model. This flags the record as isDeleted and thus removes it from all() queries on the store. The deletion can then be persisted using save(). Alternatively, you can use the destroyRecord method to delete and persist at the same time.

store.find('post', 1).then(function (post) {
 post.deleteRecord();
 post.get('isDeleted'); // => true
 post.save(); // => DELETE to /posts/1
});

// OR
store.find('post', 2).then(function (post) {
 post.destroyRecord(); // => DELETE to /posts/2
});

Pushing Records Into The Store

One way to think about the store is as a cache of all of the records that have been loaded by your application. If a route or a controller in your app asks for a record, the store can return it immediately if it is in the cache. Otherwise, the store must ask the adapter to load it, which usually means a trip over the network to retrieve it from the server.

Instead of waiting for the app to request a record, however, you can push records into the store’s cache ahead of time.

This is useful if you have a good sense of what records the user will need next. When they click on a link, instead of waiting for a network request to finish, Ember.js can render the new template immediately. It feels instantaneous.

Another use case for pushing in records is if your application has a streaming connection to a backend. If a record is created or modified, you want to update the UI immediately.

Pushing Records

To push a record into the store, call the store’s push() method.

For example, imagine we want to preload some data into the store when the application boots for the first time.

We can use the ApplicationRoute to do so. The ApplicationRoute is the top-most route in the route hierarchy, and its model hook gets called once when the app starts up.

var attr = DS.attr;

App.Album = DS.Model.extend({
 title: attr(),
 artist: attr(),
 songCount: attr()
});

App.ApplicationRoute = Ember.Route.extend({
 model: function() {
   this.store.push('album', {
     id: 1,
     title: "Fewer Moving Parts",
     artist: "David Bazan",
     songCount: 10
   });

   this.store.push('album', {
     id: 2,
     title: "Calgary b/w I Can't Make You Love Me/Nick Of Time",
     artist: "Bon Iver",
     songCount: 2
   });
 }
});

Persisting Records

Records in Ember Data are persisted on a per-instance basis. Call save() on any instance of DS.Model and it will make a network request.

Here are a few examples:

var post = store.createRecord('post', {
 title: 'Rails is Omakase',
 body: 'Lorem ipsum'
});

post.save(); // => POST to '/posts'

store.find('post', 1).then(function (post) {
 post.get('title'); // => "Rails is Omakase"

 post.set('title', 'A new post');

 post.save(); // => PUT to '/posts/1'
});

Promises

save() returns a promise, so it is extremely easy to handle success and failure scenarios. Here’s a common pattern:

var post = store.createRecord('post', {
 title: 'Rails is Omakase',
 body: 'Lorem ipsum'
});

var self = this;

function transitionToPost(post) {
 self.transitionToRoute('posts.show', post);
}

function failure(reason) {
 // handle the error
}

post.save().then(transitionToPost).catch(failure);

// => POST to '/posts'
// => transitioning to posts.show route

Promises even make it easy to work with failed network requests:

var post = store.createRecord('post', {
 title: 'Rails is Omakase',
 body: 'Lorem ipsum'
});

var self = this;

var onSuccess = function(post) {
 self.transitionToRoute('posts.show', post);
};

var onFail = function(post) {
 // deal with the failure here
};

post.save().then(onSuccess, onFail);

// => POST to '/posts'
// => transitioning to posts.show route

You can read more about promises here, but here is another example showing how to retry persisting:

function retry(callback, nTimes) {
 // if the promise fails
 return callback().catch(function(reason) {
   // if we haven't hit the retry limit
   if (nTimes-- > 0) {
     // retry again with the result of calling the retry callback
     // and the new retry limit
     return retry(callback, nTimes);
   }

   // otherwise, if we hit the retry limit, rethrow the error
   throw reason;
 });
}

// try to save the post up to 5 times
retry(function() {
 return post.save();
}, 5);

Finding Records

The Ember Data store provides a simple interface for finding records of a single type through the store object’s find method. Internally, the store uses find, findAll, and findQuery based on the supplied arguments.

The first argument to store.find() is always the record type. The optional second argument determines if a request is made for all records, a single record, or a query.

Finding All Records of a Type

1 var posts = this.store.find('post'); // => GET /posts

To get a list of records already loaded into the store, without making another network request, use all instead.

1 var posts = this.store.all('post'); // => no network request

find returns a DS.PromiseArray that fulfills to a DS.RecordArray and all directly returns a DS.RecordArray.

It’s important to note that DS.RecordArray is not a JavaScript array. It is an object that implements Ember.Enumerable. This is important because, for example, if you want to retrieve records by index, the [] notation will not work–you’ll have to use objectAt(index) instead.

Finding a Single Record

If you provide a number or string as the second argument to store.find(), Ember Data will assume that you are passing in an ID and attempt to retrieve a record of the type passed in as the first argument with that ID. This will return a promise that fulfills with the requested record:

1 var aSinglePost = this.store.find('post', 1); // => GET /posts/1

Querying For Records

If you provide a plain object as the second argument to find, Ember Data will make a GET request with the object serialized as query params. This method returns DS.PromiseArray in the same way as find with no second argument.

For example, we could search for all person models who have the name of Peter:

1 var peters = this.store.find('person', { name: "Peter" }); // => GET to /persons\
2 ?name='Peter'

Integrating with the Route’s Model Hook

As discussed in Specifying a Route’s Model, routes are responsible for telling their template which model to render.

Ember.Route’s model hook supports asynchronous values out-of-the-box. If you return a promise from the model hook, the router will wait until the promise has fulfilled to render the template.

This makes it easy to write apps with asynchronous data using Ember Data. Just return the requested record from the model hook, and let Ember deal with figuring out whether a network request is needed or not.

App.Router.map(function() {
 this.resource('posts');
 this.resource('post', { path: ':post_id' });
});

App.PostsRoute = Ember.Route.extend({
 model: function() {
   return this.store.find('post');
 }
});

App.PostRoute = Ember.Route.extend({
 model: function(params) {
   return this.store.find('post', params.post_id);
 }
})

Working With Records

Modifying Attributes

Once a record has been loaded, you can begin making changes to its attributes. Attributes behave just like normal properties in Ember.js objects. Making changes is as simple as setting the attribute you want to change:

var tyrion = this.store.find('person', 1);
// ...after the record has loaded
tyrion.set('firstName', "Yollo");

All of the Ember.js conveniences are available for modifying attributes. For example, you can use Ember.Object’s incrementProperty helper:

1 person.incrementProperty('age'); // Happy birthday!

You can tell if a record has outstanding changes that have not yet been saved by checking its isDirty property. You can also see what parts of the record were changed and what the original value was using the changedAttributes function. changedAttributes returns an object, whose keys are the changed properties and values are an array of values [oldValue, newValue].

person.get('isAdmin');      //=> false
person.get('isDirty');      //=> false
person.set('isAdmin', true);
person.get('isDirty');      //=> true
person.changedAttributes(); //=> { isAdmin: [false, true] }

At this point, you can either persist your changes via save() or you can rollback your changes. Calling rollback() reverts all the changedAttributes to their original value.

person.get('isDirty');      //=> true
person.changedAttributes(); //=> { isAdmin: [false, true] }

person.rollback();

person.get('isDirty');      //=> false
person.get('isAdmin');      //=> false
person.changedAttributes(); //=> {}

Using Fixtures

When developing client-side applications, your server may not have an API ready to develop against. The FixtureAdapter allows you to begin developing Ember.js apps now, and switch to another adapter when your API is ready to consume without any changes to your application code.

Getting Started

Using the fixture adapter entails three very simple setup steps:

Create a new store using the fixture adapter and attach it to your app.
Define your model using DS.Model.extend.
Attach fixtures(also known as sample data) to the model’s class.

Creating a Fixture Adapter

Simply attach it as the ApplicationAdapter property on your instance of Ember.Application:

1 var App = Ember.Application.create();
2 App.ApplicationAdapter = DS.FixtureAdapter;

Define Your Model

You should refer to Defining a Model for a more in-depth guide on using Ember Data Models, but for the purposes of demonstration we’ll use an example modeling people who document Ember.js.

App.Documenter = DS.Model.extend({
 firstName: DS.attr( 'string' ),
 lastName: DS.attr( 'string' )
});

Attach Fixtures to the Model Class

Attaching fixtures couldn’t be simpler. Just attach a collection of plain JavaScript objects to your Model’s class under the FIXTURES property:

App.Documenter.FIXTURES = [
 { id: 1, firstName: 'Trek', lastName: 'Glowacki' },
 { id: 2, firstName: 'Tom' , lastName: 'Dale'     }
];

That’s it! You can now use all of methods for Finding Records in your application. For example:

App.DocumenterRoute = Ember.Route.extend({
 model: function() {
   return this.store.find('documenter', 1); // returns a promise that will reso\
lve
                                            // with the record representing Tre\
k Glowacki
 }
});

Naming Conventions

Unlike the REST Adapter, the Fixture Adapter does not make any assumptions about the naming conventions of your model. As you saw in the example above, if you declare the attribute as firstName during DS.Model.extend, you use firstName to represent the same field in your fixture data.

Importantly, you should make sure that each record in your fixture data has a uniquely identifiable field. By default, Ember Data assumes this key is called id. Should you not provide an id field in your fixtures, or not override the primary key, the Fixture Adapter will throw an error.

The REST Adapter

By default, your store will use DS.RESTAdapter to load and save records. The RESTAdapter assumes that the URLs and JSON associated with each model are conventional; this means that, if you follow the rules, you will not need to configure the adapter or write any code in order to get started.

URL Conventions

The REST adapter is smart enough to determine the URLs it communicates with based on the name of the model. For example, if you ask for a Post by ID:

1 store.find('post', 1).then(function(post) {
2 });

The REST adapter will automatically send a GET request to /posts/1.

The actions you can take on a record map onto the following URLs in the REST adapter:

Pluralization Customization

Irregular or uncountable pluralizations can be specified via Ember.Inflector.inflector:

var inflector = Ember.Inflector.inflector;

inflector.irregular('formula', 'formulae');
inflector.uncountable('advice');

This will tell the REST adapter that requests for App.Formula requests should go to /formulae/1 instead of /formulas/1.

Endpoint Path Customization

Endpoint paths can be prefixed with a namespace by setting the namespace property on the adapter:

App.ApplicationAdapter = DS.RESTAdapter.extend({
 namespace: 'api/1'
});

Requests for App.Person would now target /api/1/people/1.

Host Customization

An adapter can target other hosts by setting the host property.

App.ApplicationAdapter = DS.RESTAdapter.extend({
 host: 'https://api.example.com'
});

Requests for App.Person would now target https://api.example.com/people/1.

JSON Conventions

When requesting a record, the REST adapter expects your server to return a JSON representation of the record that conforms to the following conventions.

JSON Root

The primary record being returned should be in a named root. For example, if you request a record from /people/123, the response should be nested inside a property called person:

{
 "person": {
   "firstName": "Jeff",
   "lastName": "Atwood"
 }
}

Note: Although after destroyRecord or deleteRecord/save the adapter expects an empty object e.g. {} to be returned from the server after destroying a record.

If you don’t have the option to change the data that the server responds with, you can override the DS.JSONSerializer#extractDeleteRecord, like so:

extractDeleteRecord: function(store, type, payload) {
 // payload is {delete: true} and then ember data wants to go ahead and set
 // the new properties, return null so it doesn't try to do that
 return null;
}

Attribute Names

Attribute names should be camelized. For example, if you have a model like this:

App.Person = DS.Model.extend({
 firstName: DS.attr('string'),
 lastName:  DS.attr('string'),

 isPersonOfTheYear: DS.attr('boolean')
});

The JSON returned from your server should look like this:

{
 "person": {
   "firstName": "Barack",
   "lastName": "Obama",
   "isPersonOfTheYear": true
 }
}

Irregular keys can be mapped with a custom serializer. If the JSON for the Person model has a key of lastNameOfPerson, and the desired attribute name is simply lastName, then create a custom Serializer for the model and override the normalizeHash property.

App.Person = DS.Model.extend({
 lastName: DS.attr('string')
});

App.PersonSerializer = DS.RESTSerializer.extend({
 normalizeHash: {
   lastNameOfPerson: function(hash) {
     hash.lastName = hash.lastNameOfPerson;
     delete hash.lastNameOfPerson;

     return hash;
   }
 }
});

Relationships

References to other records should be done by ID. For example, if you have a model with a hasMany relationship:

App.Post = DS.Model.extend({
 comments: DS.hasMany('comment', {async: true})
});

The JSON should encode the relationship as an array of IDs:

{
 "post": {
   "comments": [1, 2, 3]
 }
}

Comments for a post can be loaded by post.get('comments'). The REST adapter will send a GET request to /comments?ids[]=1&ids[]=2&ids[]=3.

Any belongsTo relationships in the JSON representation should be the camelized version of the Ember Data model’s name, with the string Id appended. For example, if you have a model:

App.Comment = DS.Model.extend({
 post: DS.belongsTo('post')
});

The JSON should encode the relationship as an ID to another record:

{
 "comment": {
   "post": 1
 }
}

If needed these naming conventions can be overwritten by implementing the keyForRelationship method.

App.ApplicationSerializer = DS.RESTSerializer.extend({
  keyForRelationship: function(key, relationship) {
     return key + 'Ids';
  }
});

Sideloaded Relationships

To reduce the number of HTTP requests necessary, you can sideload additional records in your JSON response. Sideloaded records live outside the JSON root, and are represented as an array of hashes:

{
 "post": {
   "id": 1,
   "title": "Node is not omakase",
   "comments": [1, 2, 3]
 },

 "comments": [{
   "id": 1,
   "body": "But is it _lightweight_ omakase?"
 },
 {
   "id": 2,
   "body": "I for one welcome our new omakase overlords"
 },
 {
   "id": 3,
   "body": "Put me on the fast track to a delicious dinner"
 }]
}

Creating Custom Transformations

In some circumstances, the built in attribute types of string, number, boolean, and date may be inadequate. For example, a server may return a non-standard date format.

Ember Data can have new JSON transforms registered for use as attributes:

App.CoordinatePointTransform = DS.Transform.extend({
 serialize: function(value) {
   return [value.get('x'), value.get('y')];
 },
 deserialize: function(value) {
   return Ember.create({ x: value[0], y: value[1] });
 }
});

App.Cursor = DS.Model.extend({
 position: DS.attr('coordinatePoint')
});

When coordinatePoint is received from the API, it is expected to be an array:

{
 cursor: {
   position: [4,9]
 }
}

But once loaded on a model instance, it will behave as an object:

var cursor = App.Cursor.find(1);
cursor.get('position.x'); //=> 4
cursor.get('position.y'); //=> 9

If position is modified and saved, it will pass through the serialize function in the transform and again be presented as an array in JSON.

Connecting to an HTTP Server

If your Ember application needs to load JSON data from an HTTP server, this guide will walk you through the process of configuring Ember Data to load records in whatever format your server returns.

The store uses an object called an adapter to know how to communicate over the network. By default, the store will use DS.RESTAdapter, an adapter that communicates with an HTTP server by transmitting JSON via XHR.

This guide is divided into two sections. The first section covers what the default behavior of the adapter is, including what URLs it will request records from and what format it expects the JSON to be in.

The second section covers how to override these default settings to customize things like which URLs data is requested from and how the JSON data is structured.

URL Conventions

The REST adapter uses the name of the model to determine what URL to send JSON to.

For example, if you ask for an App.Photo record by ID:

App.PhotoRoute = Ember.Route.extend({
 model: function(params) {
   return this.store.find('photo', params.photo_id);
 }
});

The REST adapter will automatically send a GET request to /photos/1.

The actions you can take on a record map onto the following URLs in the REST adapter:

JSON Conventions

Given the following models:

App.Post = DS.Model.extend({
 title:    DS.attr(),
 comments: DS.hasMany('comment'),
 user:     DS.belongsTo('user')
});

App.Comment = DS.Model.extend({
 body: DS.attr()
});

Ember Data expects that a GET request to /posts/1 would return the JSON in the following format:

{
 "post": {
   "id": 1,
   "title": "Rails is omakase",
   "comments": ["1", "2"],
   "user" : "dhh"
 },

 "comments": [{
   "id": "1",
   "body": "Rails is unagi"
 }, {
   "id": "2",
   "body": "Omakase O_o"
 }]
}

To quickly prototype a model and see the expected JSON, try using the Ember Data Model Maker by Andy Crum.

Customizing the Adapter

To customize the REST adapter, define a subclass of DS.RESTAdapter and name it App.ApplicationAdapter. You can then override its properties and methods to customize how records are retrieved and saved.

Customizing a Specific Model

It’s entirely possible that you need to define options for just one model instead of an application-wide customization. In that case, you can create an adapter named after the model you are specifying:

App.PostAdapter = DS.RESTAdapter.extend({
 namespace: 'api/v2',
 host: 'https://api.example2.com'
});

App.PhotoAdapter = DS.RESTAdapter.extend({
 namespace: 'api/v1',
 host: 'https://api.example.com'
});

This allows you to easily connect to multiple API versions simultaneously or interact with different domains on a per model basis.

Customizing URLs

URL Prefix

If your JSON API lives somewhere other than on the host root, you can set a prefix that will be added to all requests.

For example, if you are using a versioned JSON API, a request for a particular person might go to /api/v1/people/1.

In that case, set namespace property to api/v1.

App.ApplicationAdapter = DS.RESTAdapter.extend({
 namespace: 'api/v1'
});

Requests for a person with ID 1 would now go to /api/v1/people/1.

URL Host

If your JSON API runs on a different domain than the one serving your Ember app, you can change the host used to make HTTP requests.

Note that in order for this to work, you will need to be using a browser that supports CORS, and your server will need to be configured to send the correct CORS headers.

To change the host that requests are sent to, set the host property:

App.ApplicationAdapter = DS.RESTAdapter.extend({
 host: 'https://api.example.com'
});

Requests for a person with ID 1 would now target https://api.example.com/people/1.

Custom HTTP Headers

Some APIs require HTTP headers, e.g. to provide an API key. Arbitrary headers can be set as key/value pairs on the RESTAdapter’s headers property and Ember Data will send them along with each ajax request.

For Example

App.ApplicationAdapter = DS.RESTAdapter.extend({
 headers: {
   'API_KEY': 'secret key',
   'ANOTHER_HEADER': 'Some header value'
 }
});

Requests for any resource will include the following HTTP headers.

1 ANOTHER_HEADER: Some header value
2 API_KEY: secret key

Handling Metadata

Along with the records returned from your store, you’ll likely need to handle some kind of metadata. Metadata is data that goes along with a specific model or type instead of a record.

Pagination is a common example of using metadata. Imagine a blog with far more posts than you can display at once. You might query it like so:

var result = this.store.find("post", {
 limit: 10,
 offset: 0
});

To get different pages of data, you’d simply change your offset in increments of 10. So far, so good. But how do you know how many pages of data you have? Your server would need to return the total number of records as a piece of metadata.

By default, Ember Data’s JSON deserializer looks for a meta key:

{
 "post": {
   "id": 1,
   "title": "Progressive Enhancement is Dead",
   "comments": ["1", "2"],
   "links": {
     "user": "/people/tomdale"
   },
   // ...
 },

 "meta": {
   "total": 100
 }
}

The metadata for a specific type is then set to the contents of meta. You can access it either with store.metadataFor, which is updated any time any query is made against the same type:

1 var meta = this.store.metadataFor("post");

Or you can access the metadata just for this query:

1 var meta = result.get("content.meta");

Now, meta.total can be used to calculate how many pages of posts you’ll have.

You can also customize metadata extraction by overriding the extractMeta method. For example, if instead of a meta object, your server simply returned:

{
 "post": [
   // ...
 ],
 "total": 100
}

You could extract it like so:

App.ApplicationSerializer = DS.RESTSerializer.extend({
 extractMeta: function(store, type, payload) {
   if (payload && payload.total) {
     store.metaForType(type, { total: payload.total });  // sets the metadata f\
or "post"
     delete payload.total;  // keeps ember data from trying to parse "total" as\
a record
   }
 }
});

Customizing Adpters

In Ember Data, the logic for communicating with a backend data store lives in the Adapter. Ember Data’s Adapter has some built-in assumptions of how a REST API should look. If your backend conventions differ from these assumptions Ember Data makes it easy to change its functionality by swapping out or extending the default Adapter.

Some reasons for customizing an Adapter include using underscores_case in your urls, using a medium other than REST to communicate with your backend API or even using a local backend.

Extending Adapters is a natural process in Ember Data. Ember takes the position that you should extend an adapter to add different functionality instead of adding a flag. This results in code that is more testable, easier to understand and reduces bloat for people who may want to subclass your adapter.

If your backend has some consistent rules you can define an ApplicationAdapter. The ApplicationAdapter will get priority over the default Adapter, however it will still be superseded by model specific Adapters.

App.ApplicationAdapter = DS.RESTAdapter.extend({
 // Application specific overrides go here
});

If you have one model that has exceptional rules for communicating with its backend than the others you can create a Model specific Adapter by naming an adapter “ModelName” + “Adapter”.

App.PostAdapter = DS.RESTAdapter.extend({
 namespace: 'api/v1'
});

By default Ember Data comes with several builtin adapters. Feel free to use these adapters as a starting point for creating your own custom adapter.

DS.Adapter is the basic adapter with no functionality. It is generally a good starting point if you want to create an adapter that is radically different from the other Ember adapters.
DS.FixtureAdapter is an adapter that loads records from memory. Its primarily used for development and testing.
DS.RESTAdapter is the most commonly extended adapter. The RESTAdapter allows your store to communicate with an HTTP server by transmitting JSON via XHR. Most Ember.js apps that consume a JSON API should use the REST adapter.
DS.ActiveModelAdapter is a specialized version of the RESTAdapter that is set up to work out of the box with Rails-style REST APIs.

Customizing the RESTAdapter

The DS.RESTAdapter is the most commonly extended adapter that ships with Ember Data. It has a handful of hooks that are commonly used to extend it to work with non-standard backends.

Endpoint Path Customization

The namespace property can be used to prefix requests with a specific url namespace.

App.ApplicationAdapter = DS.RESTAdapter.extend({
 namespace: 'api/1'
});

Requests for App.Person would now target /api/1/people/1.

Host Customization

By default the adapter will target the current domain. If you would like to specify a new domain you can do so by setting the host property on the adapter.

App.ApplicationAdapter = DS.RESTAdapter.extend({
 host: 'https://api.example.com'
});

Requests for App.Person would now target https://api.example.com/people/1.

Path Customization

By default the RESTAdapter will attempt to pluralize and camelCase the model name to generate the path name. If this convention does not conform to your backend you can override the pathForType method.

For example, if you did not want to pluralize model names and needed underscore_case instead of camelCase you could override the pathForType method like this:

App.ApplicationAdapter = DS.RESTAdapter.extend({
 pathForType: function(type) {
   return Ember.String.underscore(type);
 }
});

Requests for App.Person would now target /person/1. Requests for App.UserProfile would now target /user_profile/1.

Authoring Adapters

The defaultSerializer property can be used to specify the serializer that will be used by this adapter. This is only used when a model specific serializer or ApplicationSerializer are not defined.

In an application, it is often easier to specify an ApplicationSerializer. However, if you are the author of a community adapter it is important to remember to set this property to ensure Ember does the right thing in the case a user of your adapter does not specify an ApplicationSerializer.

MyCustomAdapterAdapter = DS.RESTAdapter.extend({
 defaultSerializer: '-default'
});

Community Adapters

If none of the builtin Ember Data Adapters work for your backend, be sure to check out some of the community maintained Ember Data Adapters. Some good places to look for Ember Data Adapters include:

GitHub
Bower

Frequently Asked Questions

Should I use a query or a filter to search records?

It depends on how many records you want to search and whether they have been loaded into the store.

Queries are useful for doing searches of hundreds, thousands, or even millions of records. You just hand the search options to your server, and it is responsible for handing you back the list of records that match. Because the response from the server includes the ID of all of the records that matched, it doesn’t matter if the store hadn’t loaded them previously; it sees that they are not in the cache and can request the records by ID if necessary.

The downside of queries is that they do not live update, they are slower, and they require that your server support the kind of queries that you wish to perform.

Because the server decides which records match the query, not the store, queries do not live update. If you want to update them, you must manually call reload() and wait for the server to respond. If you create a new record on the client, it will not show up in the results until you both save the new record to the server and reload the query results.

Because the store must confer with your server to determine the results of a query, it necessitates a network request. This can feel slow to users, especially if they are on a slow connection or your server is slow to respond. The typical speed of JavaScript web applications can heighten the perceived slowness when the server must be consulted.

Lastly, performing queries requires collaboration between the store and your server. By default, Ember Data will send the search options that you pass as the body of an HTTP request to your server. If your server does not support requests in this format, you will need to either change your server to do so, or customize how queries are sent by creating a custom adapter.

Filters, on the other hand, perform a live search of all of the records in the store’s cache. As soon as a new record is loaded into the store, the filter will check to see if the record matches, and if so, add it to the array of search results. If that array is displayed in a template, it will update automatically.

Filters also take into account newly created records that have not been saved, and records that have been modified but not yet saved. If you want records to show up in search results as soon as they are created or modified on the client, you should use a filter.

Keep in mind that records will not show up in a filter if the store doesn’t know about them. You can ensure that a record is in the store by using the store’s push() method.

There is also a limit to how many records you can reasonably keep in memory and search before you start hitting performance issues.

Finally, keep in mind that you can combine queries and filters to take advantage of their respective strengths and weaknesses. Remember that records returned by a query to the server are cached in the store. You can use this fact to perform a filter, passing it a query that starts matching records into the store, and a filter function that matches the same records.

This will offload searching all of the possible records to the server, while still creating a live updating list that includes records created and modified on the client.

App.PostsFavoritedRoute = Ember.Route.extend({
 model: function() {
   var store = this.store;

   // Create a filter for all favorited posts that will be displayed in
   // the template. Any favorited posts that are already in the store
   // will be displayed immediately;
   // Kick off a query to the server for all posts that
   // the user has favorited. As results from the query are
   // returned from the server, they will also begin to appear.
   return store.filter('post', { favorited: true }, function(post) {
     return post.get('isFavorited');
   });
 }
});

How do I inform Ember Data about new records created on the backend?

When you request a record using Ember Data’s store.find method, Ember will automatically load the data into the store. This allows Ember to avoid the latency of making a round trip to the backend next time that record is requested. Additionally, loading a record into the store will update any RecordArrays (e.g. the result of store.filter or store.all) that should include that record. This means any data bindings or computed properties that depend on the RecordArray will automatically be synced to include the new or updated record values.

Some applications may want to add or update records in the store without requesting the record via store.find. To accomplish this you can use the DS.Store’s push, pushPayload, or update methods. This is useful for web applications that have a channel (such as SSE or Web Sockets) to notify it of new or updated records on the backend.

push is the simplest way to load records to Ember Data’s store. When using push it is important to remember to deserialize the JSON object before pushing it into the store. push only accepts one record at a time. If you would like to load an array of records to the store you can call pushMany.

socket.on('message', function (message) {
 var type = store.modelFor(message.model);
 var serializer = store.serializerFor(type.typeKey);
 var record = serializer.extractSingle(store, type, message.data);
 store.push(message.model, record);
});

pushPayload is a convenience wrapper for store#push that will deserialize payloads if the model’s Serializer implements a pushPayload method. It is important to note this method will not work with the JSONSerializer because it does not implement a pushPayload method.

socket.on('message', function (message) {
 store.pushPayload(message.model, message.data);
});

update works like a push except it can handle partial attributes without overwriting the existing record properties. This method is useful if your web application only receives notifications of the changed attributes on a model. Like push it is important to remember to deserialize the JSON object before calling update.

socket.on('message', function (message) {
 var hash = message.data;
 var type = store.modelFor(message.model);
 var fields = Ember.get(type, 'fields');
 fields.forEach(function(field) {
   var payloadField = Ember.String.underscore(field);
   if (field === payloadField) { return; }
     hash[field] = hash[payloadField];
     delete hash[payloadField];
 });
 store.push(message.model, hash);
});

Up next

Views