More consistent resource linkage.

[dgeb]

I put together this PR as the result of a discussion in #437. As I mentioned, this was one approach that I considered while working on RC2, but was concerned with the verbosity.

However, after discussing with a couple implementors who are in favor of these simplifications, I'd like to put this out there for general consideration. Even though this is the 11th hour for the spec, it's probably worthwhile to consider a simplifying approach.

The gist is that resource linkage is consistently represented in this approach, regardless of whether relationships are homogeneous or heterogeneous. Linkage is contained within a linkage member in the links object, eliminating the dichotomy of using either type / id (for homogeneous relationships) vs. data (for heteregeneous relationships).

Here's the home page resource object currently:

  "data": [{
    "type": "posts",
    "id": "1",
    "title": "JSON API paints my bikeshed!",
    "links": {
      "self": "http://example.com/posts/1",
      "author": {
        "self": "http://example.com/posts/1/links/author",
        "related": "http://example.com/posts/1/author",
        "type": "people",
        "id": "9"
      },
      "comments": {
        "self": "http://example.com/posts/1/links/comments",
        "related": "http://example.com/posts/1/comments",
        "type": "comments",
        "id": ["5", "12"]
      }
    }
  }]

And here it is after this change:

  "data": [{
    "type": "posts",
    "id": "1",
    "title": "JSON API paints my bikeshed!",
    "links": {
      "self": "http://example.com/posts/1",
      "author": {
        "self": "http://example.com/posts/1/links/author",
        "related": "http://example.com/posts/1/author",
        "linkage": {"type": "people", "id": "9"}
      },
      "comments": {
        "self": "http://example.com/posts/1/links/comments",
        "related": "http://example.com/posts/1/comments",
        "linkage": [
           {"type": "comments", "id": "5"},
           {"type": "comments", "id": "12"}
        ]
      }
    }
  }]

I find this structure to be more consistent with resource objects themselves, which all must contain a type and id. This approach also simplifies endpoints for updating relationships.

But of course, as I've said, it is more verbose.

[bintoro]

In favor 👍

A further benefit not mentioned in @dgeb's comment is that this eliminates the need to maintain a separate format for relationship URL representations.

[tkellen]

👍 here too.

[lgebhardt]

👍 from me too

[hhware]

IMHO, a great improvement!

[ColtonProvias]

Also in favor.

[gr0uch]

It should have been this way from the start if you wanted to support heterogeneous relationships. +1

[nwjsmith]

I think the trade-off in verbosity is fine if it means better consistency. This also might make it easier to write a client-side caching that looks up by a key based on type and id.

🚀

[dgeb]

With all in favor and no objections, I'm merging.

[kjwierenga]

:+1 This is indeed more consistent and gets rid of the ugly 'data' member in resource relationsships.

Op 11 mrt. 2015, om 11:48 heeft Dan Gebhardt notifications@github.com het volgende geschreven:

Merged #447 #447.

—
Reply to this email directly or view it on GitHub #447 (comment).

[ethanresnick]

+1 on this too!

[hhware]

@dgeb The only time the word "heterogeneous" is mentioned in the spec is a non-normative note. I think it would be useful to provide at least some examples for it, to make it clearer why the resource type needs to be specified twice, in the URL / linkage name and inside the linkage itself. E.g., examples could be provided for creating and updating heterogeneous relationships. Would there be any intetrest in such examples, or they were omitted intentionally?