# Contradictory Guides on JSON API Conventions **URL:** \ **Category:** Ember Data\ **Created:** [December 12, 2013, 7:41pm UTC](https://discuss.emberjs.com/t/contradictory-guides-on-json-api-conventions/3588 "2013-12-12T19:41:24Z")\ **Posts on this page:** 5\ **Page:** 1
**Author:** ![smackesey](https://sea1.discourse-cdn.com/flex019/user_avatar/discuss.emberjs.com/smackesey/32/14011_2.png) [@smackesey](https://discuss.emberjs.com/u/smackesey)\ **Post date:** [December 12, 2013, 7:41pm UTC](https://discuss.emberjs.com/t/contradictory-guides-on-json-api-conventions/3588/1 "2013-12-12T19:41:24Z")
Two Ember guides on JSON API conventions to use with Ember Data are contradictory: #### [RESTAdapter guide](http://emberjs.com/guides/models/the-rest-adapter/#toc_relationships) This guide says that relationships should be captured in the API by appending “\_ids” to the related model name, as in: ``` { "post": { "comment_ids": [1, 2, 3] } } ``` It also shows that the ids are integers, and says that API property keys should be underscored versions of their Ember model equivalents. #### [Connecting to an HTTP Server guide](http://emberjs.com/guides/models/connecting-to-an-http-server/#toc_json-conventions) This guide says that relationships should be captured in the API without appending “\_ids”: ``` "post": { "comments": ["1", "2"], } ``` It also shows that the ids are strings. If you look at the link, it also sort of implies that related records need to be sideloaded into the API response, which they do not. * * * The **Connecting to an HTTP Server** guide is linked in the main sidebar of the Ember guides site. I cannot find a link to the **RESTAdapter Guide** in this sidebar, but it comes up on Google. The **RESTAdapter Guide** contains generally more information than the **Connecting to an HTTP Server Guide**. _Which guide am I supposed to believe?_ I remember trying to work with Ember months ago and encountering similar issues with the JSON API conventions; at the time, I believe the guides linked to [jsonapi.org](http://jsonapi.org), which specifies yet ANOTHER standard. #### Questions - I am finding that Ember data is not capturing my properties when the API keys them in the underscored form, but they are correctly captured when the API uses exactly the same key as is used in my Ember model. This is in direct contradiction of the **RESTAdapter guide**. How should the API key properties? - Should ids be strings or integers, or does it not matter? - Should “\_ids”/“\_id” be appended to properties holding the ids of related records? - Is there some simple location that I can always consult for a complete specification of the conventions used by the Ember Data REST Adapter? #### Versions I am currently using the latest builds of both Ember and Ember Data: - 1.3.0-beta.2 (Ember) - 1.0.0-beta.3 (Ember Data) I decided to use the latest after having needed to update versions several times in order to make some of my code work. Not sure whether using the latest betas is a good idea though. What versions of Ember can I expect Ember Data to work properly with? The Bower repository of the latest Ember data has ~1.0.0 for its Ember version specification. I found that I needed a version of Ember \>1.1.0 to fix certain bugs. Is this safe, or do I really need to confine myself to Ember ~1.0.0 with Ember Data? ---
**Author:** ![turboladen](https://sea1.discourse-cdn.com/flex019/user_avatar/discuss.emberjs.com/turboladen/32/14860_2.png) [@turboladen](https://discuss.emberjs.com/u/turboladen)\ **Post date:** [December 25, 2013, 5:28pm UTC](https://discuss.emberjs.com/t/contradictory-guides-on-json-api-conventions/3588/2 "2013-12-25T17:28:58Z")
I don’t mean to hijack, but rather add to the topic. The contradiction that I’ve been wondering about lately revolves around singular vs. plural resource names. For example, [JSON:API — Latest Specification (v1.0)](http://jsonapi.org/format) shows the following for creating a photo: ```auto POST /photos Content-Type: application/vnd.api+json Accept: application/vnd.api+json { "photos": [{ "title": "Ember Hamster", "src": "http://example.com/images/productivity.png" }] } ``` …yet all examples I see on the ember guides show examples using the singular form (like the examples OP posted). I’m in the middle of documenting my API as well as building it for use with Ember and not sure which route to take. Seems like if I want things to work, I follow the Ember docs, yet if I want to “be to spec” then I follow the [jsonapi.org](http://jsonapi.org) docs. Hopefully this reply adds to the OP’s post… ---
**Author:** ![wdmeldon](https://sea1.discourse-cdn.com/flex019/user_avatar/discuss.emberjs.com/wdmeldon/32/15379_2.png) [@wdmeldon](https://discuss.emberjs.com/u/wdmeldon)\ **Post date:** [December 26, 2013, 1:15pm UTC](https://discuss.emberjs.com/t/contradictory-guides-on-json-api-conventions/3588/3 "2013-12-26T13:15:13Z")
The JSON API standard was based on Ember Data, but the two diverged substantially a while back. I believe the current approach is to implement the standard as an adapter Someone already started one [here](https://github.com/daliwali/ember-json-api "JSON API Adapter") As far as what the ACTUAL format ED consumes, it’s such a moving target I really am never all that sure. Hopefully this will be addressed sooner rather than later. The best source of documentation right now is the code. ---
**Author:** ![fayimora](https://sea1.discourse-cdn.com/flex019/user_avatar/discuss.emberjs.com/fayimora/32/14385_2.png) [@fayimora](https://discuss.emberjs.com/u/fayimora)\ **Post date:** [December 27, 2013, 3:31am UTC](https://discuss.emberjs.com/t/contradictory-guides-on-json-api-conventions/3588/4 "2013-12-27T03:31:06Z")
Just ran into this too. > [@smackesey](#): > > This guide says that relationships should be captured in the API by appending “\_ids” to the related model name, as in: > > { “post”: { “comment\_ids”: [1, 2, 3] } } > > It also shows that the ids are integers, and says that API property keys should be underscored versions of their Ember model equivalents. It actually says `commentIds` not `comment_ids`. To add to that, the RESTAdapter guide uses plain ints `[1,2,3]` while the HTTP Server guide uses strings `["1", "2", "3"]` so which is it? ---
**Author:** ![smackesey](https://sea1.discourse-cdn.com/flex019/user_avatar/discuss.emberjs.com/smackesey/32/14011_2.png) [@smackesey](https://discuss.emberjs.com/u/smackesey)\ **Post date:** [December 27, 2013, 3:27pm UTC](https://discuss.emberjs.com/t/contradictory-guides-on-json-api-conventions/3588/5 "2013-12-27T15:27:39Z")
> [@fayimora](#): > > It actually says commentIds not comment\_ids. This is new-- looks like the [RESTAdapter guide](http://emberjs.com/guides/models/the-rest-adapter/#toc_relationships) was recently updated. They also changed the stated convention for naming keys in your JSON. It now says they should be camelized, not underscored. Unfortunately, the guide still contradicts the [Connecting to an HTTP Server](http://emberjs.com/guides/models/connecting-to-an-http-server/#toc_json-conventions) guide regarding the key for associated ids (`comments` vs `commentIds`), but since it was most recently updated it looks like the RESTAdapter guide is the way to go.