Series: Introduction to Ember Data 2.0

Ember Data 2.0-Essential Adapter Customizations

Published on Jan 20, 2016

There are a huge array of customization options available to users of the RESTAdapter and JSONAPIAdapter. In this episode we narrow it down to the 5 most common.

We track the URL, HTTP Method, and query params for 7 different endpoints, watching them change as we customize our Adapter class.


Links

Code

There are many ways to customize Ember Data Adapters. This screencast covers the most popular.

Some change the URL itself:

export default DS.RESTSerializer.extend({
    namespace: 'api/v1',
    host: 'www.tacodeli.com',
    pathForType(modelName){
        return Ember.String.capitalize(modelName);
    }
})

The three above apply to all of the URLs, turning the findRecord URL for 'taco' from /taco to www.tacodeli.com/api/v1/Taco.

headers is just a hash that automatically attaches headers based on the calculated values. More details here.

isSuccess and isInvalid and used by handleResponse to decide what to do with the response.

export default DS.RESTSerializer.extend({
  isSuccess: function(status, headers, payload) {
    return status >= 200 && status < 300 || status === 304;
  },
  isInvalid: function(status, headers, payload) {
    return status === 422;
  }
})

Deeper customizations will be covered next episode.

Transcript

Hey and welcome back to our series on Ember Data Adapters and Serializers. Today we’re going to be exploring adapters more in depth, getting into some of the more common customizations for adapters. In this week’s pro-episode, we’ll get into some even more in-depth customizations you can make.

So in the DS.Adapter base class, it gives us these methods. These are the core methods that need to be implemented. Those are the ones that are the core of DS.Adapter. Everything else is to serve those. And what they do is they basically they give you a URL and then they call that URL. I happen to have hijacked some of these so that instead of calling the URL, they just post it here. And so we’ll use this to help explore the different ways we can customize your adapter. So first let’s do a rundown of the different methods that we have here.

So we have createRecord which will send something to the server that will create a record. And notice I have the name first. That’s what it’s called within the Ember Data Adapter. Then I have the HTTP method that’s used. Then I have the URL that it’s sent to, and then I have any additional query params that are sent up with it. Notice that there is other data that’s being sent. We’re posting a taco here so it would send up data about that taco, but that’s controlled by the serializer, and so we won’t think about that during this time. We’ll just worry about the query params such as when you’re doing the query.

Alright, so we can create a record, update the record, delete the record, find all of the records, we can query and queryRecord, and I believe query returns an array and queryRecord just turns one. And then we have findRecord which just gets us one record.

It’s worth noting that the RESTAdapter which we’re using today has three other ones like this, findBelongsTo, findHasMany, and findMany. However, these go off of the links that are given in the data. I couldn’t get that working generically and it’s not part of the core DS.Adapter, so we’re going to skip over it for now.

Now we’re ready to customize our adapter. Alright, so we’ll start with the most common one, which is namespace, so let’s say the namespace is api/v1. So you’ll see that it attaches that before what it had before, so it attaches it to the beginning but doesn’t attach it completely to the beginning because there’s also the host attribute which it’ll attach before that.

So without the host attribute, it’s assuming that it’s hosted at the same place as you’re serving your Ember app from, and that might not always be the case. The host you’ll probably want to change on an adapter by adapter basis a lot of the time rather than in the application, say if you’re calling out to GitHub or something like that.

A third common edit is pathForType. So this is the default pathForType in the RESTAdapter. So what it does is it takes the modelName, it camelizes it and then it pluralizes it. So you’ll see here that it’s pluralized taco, and then for taco-taco, it camelizes it and pluralizes it.

So we’ll see the change when we define our own pathForType. We’ll take the modelName and then we’ll just return it. And this is all singularized and this is singularized and this is both singularized and not camelCase.

Of course you can do more than just return the plain modelName and getting rid of the default pathForType. I’ll leave those exact details up to the twisted imagination of whoever designed your API.

There are two other modifications that I want to show you today that are still fairly common, they just aren’t as visible on this example I’ve made. So the first is headers, and it’s fairly straightforward, it’s just a hash of headers that you send. As you can see, they can be dynamic. You should note if you use a dynamic header that sometimes that dynamicism isn’t within the Ember Observer system, so you may have to call .volatile on that function.

Alright, and the second set of customizations are the isInvalid and isSuccess methods. So they’re used by handleResponse to decide whether the response is a success or a failure. And the defaults are fairly straightforward. If it’s greater than 200, less than 300, or it’s 304, then it’s a success. However, your server might not send back status codes like that, or it might send weird custom status codes. So isSuccess and isInvalid is a place to accommodate those.

So in this episode, we were introduced to the core methods of the adapter and roughly what they do. And we saw how several different things can modify them. Several of the most common modifications are host, namespace, headers, isInvalid and isSuccess, and pathForType. We also saw that at least in the REST Adapter, there are several ones that are just for getting relationships.

In the next episode, we’re going to be going over several of these other things, like buildURL, the urlFor set of methods, and the reloading set of methods, as well as several others. I hope to see you then.

Introduction to Ember Data 2.0

Subscribe to our mailing list