json-api/json-api — pull request #120 by imanel (2013-07-06 05:32:11+00:00)
Title: Proposal: expose difference between id-based and url-based API

With current specification both id-based and url-based API have the same syntax and you need to guess which one should be applied. From my perspective this might be confusing and probably should be avoided. Because of that I would like to suggest adding type-specific suffixes both of them as shown below.

### ID-based API

**Current version**

```
{
"posts": [{
"id": "1",
"title": "Rails is Omakase",
"links": {
"author": "9",
"comments": [ "5", "12", "17", "20" ]
}
}]
}
```

**Proposal:**

```
{
"posts": [{
"id": "1",
"title": "Rails is Omakase",
"links": {
"author_di": "9",
"comment_ids": [ "5", "12", "17", "20" ]
}
}]
}
```

### URL-based API

**Current version**

```
{
"posts": [{
"id": "1",
"title": "Rails is Omakase",
"links": {
"author": "http://example.com/people/1",
"comments": "http://example.com/comments/5,12,17,20"
}
}]
}
```

**Proposal:**

```
{
"posts": [{
"id": "1",
"title": "Rails is Omakase",
"links": {
"author_url": "http://example.com/people/1",
"comments_url": "http://example.com/comments/5,12,17,20"
}
}]
}
```

### URL Template Shorthands

**Current version**

```
{
"links": {
"posts.comments": "http://example.com/comments/{posts.comments}"
},
"posts": [{
"id": "1",
"title": "Rails is Omakase",
"links": {
"comments": [ "1", "2", "3", "4" ]
}
}]
}
```

**Proposal:**

```
{
"links": {
"posts.comments": "http://example.com/comments/{posts.comment_ids}"
},
"posts": [{
"id": "1",
"title": "Rails is Omakase",
"links": {
"comment_ids": [ "1", "2", "3", "4" ]
}
}]
}
```