Contradictory Guides on JSON API Conventions

Ember Data
1

Two Ember guides on JSON API conventions to use with Ember Data are contradictory:

RESTAdapter guide

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

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, 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?

2 Likes
2

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) shows the following for creating a photo:

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 docs.

Hopefully this reply adds to the OP’s post…

1 Like
3

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

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.

4

Just ran into this too.

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?

5

This is new-- looks like the RESTAdapter guide 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 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.