[JsonApiSerializer] Relationship can't be called links

[adiachenko]

JsonApiSerializer arbitrarily merges links attribute on a Model with document (resource) links in a response.

Apparently, it's not a bug and is done explicitly in the item method of serializer, but this behavior violates JSON API spec as there are clear requirements as to what should go into link object and clashes with quite a few popular use cases.

Imagine Goodreads where each book has links (e.g. Amazon, Google Play etc.). If Goodreads built an API using Fractal, they'll have this:

"links": {
  "0": {
    "id": 0,
    "text": "Amazon",
    "url": "https://www.amazon.com/whatever",
  },
  "self": "http://goodreads.com/api/v1/books/1"
},

instead of

"links": {
  "self": "http://goodreads.com/api/v1/books/1"
},

I hope this example clears the confusion as to what the issue is.

[adiachenko]

This is quite easy to fix, but I don't understand why the merge is happening in the first place. Would the PR for this be welcomed?

[matt-allan]

This is a problem with id or type too.

Right now the transformer only really has the transform method, so the JsonApiSerializer hoists the data it needs out of the returned array. Using the links was added in #284. That was technically a breaking change because it makes links a reserved word.

IMO it would make more sense for the transformer to have additional method hooks for this stuff:

class Transformer
{
    function transform($data): array {}
    function id($data): string {}
    function type($data): string {}
}

If the serializer is going to continue hoisting the attributes, it should probably be prefixing them to reduce collisions (_links, _type etc) or put them in their own key.

[Indemnity83]

id and type already are reserved words per the JSON API spec.

A resource object’s attributes and its relationships are collectively called its “fields”.

Fields for a resource object MUST share a common namespace with each other and with type and id. In other words, a resource can not have an attribute and relationship with the same name, nor can it have an attribute or relationship named type or id.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 4 weeks if no further activity occurs. Thank you for your contributions.