json-api/json-api — pull request #143 by dgeb (2013-11-01 16:52:19+00:00)
Title: Separate related resources in a top-level `linked` object.

It's important to separate the primary resource from related resources because:

* It allows the client to easily identify the primary resource among related resources of the same type. This is especially important when creating a resource without prior knowledge of its server-assigned id.
* It clarifies issues like pagination that are specific to the primary resource.

This can be achieved by nesting related resources in a `linked` object. For instance:

```javascript
{
"posts": [{
"id": "1",
"name": "Rails is Omakase",
"links": {
"author": "9",
"related": ["2"]
}
}],
"linked": {
"posts": [{
"id": "2",
"name": "The Parley Letter",
"links": {
"author": "9",
"related": ["1"]
}
}],
"people": [{
"id": "9",
"name": "DHH"
}]
}
}
```

It's easy to imagine a scenario in which resources that are members of the primary array are secondary resources for other members of the primary array (e.g. people + friends). In those scenarios, primary resources should not be duplicated as secondary resources in `linked`. In other words, a single canonical representation of a resource should continue to be returned with each response.

[Closes #74]