ember-data-api-notes.md

Ember data conventions

Model

App.Customer = DS.Model.extend({
  firstName:attr('string'),
  address:belongsTo('address')
});

App.Address = DS.Model.extend({
  street:attr('string')
});

Note that an id attribute is implicitly created for every model. By default, whenever ember-data requests records from the server, it expects the response to be in what's known as a 'side-loaded' format. A side-loaded response is simply a reference based JSON object where instead of embedding the address in the JSON structure of the Customer response, you include the address at the same level in teh JSON object as the customer and instead only use the address ID. i.e. to return a customer with ID 1 that has the address with ID 5 you would produce the following JSON...

{
  "customer":{
    "id" : 1
    "firstName" : "Courtney",
    "address" : 5
  },
  "address" : {
    "id" : 5
    "street" : "Earl's Ave"
  }
}

There are numerous advantages to side loaded records but for an existing application you probably would include the address directly in the customer object and would not have "customer" and "address" as fields. Ember supports this as well using what's known as embedded records...they require additional work client side but would mean existing server side code stays the same.

Endpoints

Given a model 'customer', ember-data expects the following API endpoints

Verb	URL	Action
GET	/customers	Find all
GET	/customers?optional=arguments	Find by property
GET	/customers/id	Find by ID
GET	/customers?ids[]=1&ids[]=N	Find by multiple IDs
POST	/customers	Create
PUT	/customers/id	Update
DELETE	/customers/id	Delete

Endpoint purpose

GET /customers<?optional=arguments>

This end point is used to fetch N number of customer records. Query parameters are optionally included. If for example you call this.store.find('customer',{firstName:'Courtney'}), ember data will make a request to GET /customers?firstName=Courtney.

GET /customers/

This end point is used to fetch the record for the customer with the ID included in the URL.

POST /customers

This endpoint is used to create a new customer record. The response is expected to be the newly created record with an ID assigned.

PUT /customers/

This endpoint is used to update the existing customer record with the ID included in the url. The response is expected to be the same record with the same ID. i.e. the ID of the response object should be the same as the one ember-data sent.

More info in the official docs:

Rest Adapter Rest Adapter class/API Meta data