WIP: Updated JSON-API to match 1.0 format

[groyoh]

Changes:

• "links" is now separated into a "relationships" object and a "links" object.
• "linkage" has been changed to "data".
• null/empty relationships are now properly rendered

[janko]

Awesome work, by the way, we this PR almost all of JSON API spec should be implemented.

There is, however, one case I would like to mention, since you your PR suggests that now Yaks will fully conform to the JSON-API spec. I think null resources aren't handled properly. If a has_one relationship is included in the resource, and it's null, as far as I remember from the JSON-API spec, the JSON should be

{
  "type": "post",
  "relationships": {
    "author": null
  }
}

Currently Yaks just ignores keys of missing associations. For has_many I think it should be an empty array.

[janko]

One other thing, in the JSON API specification it says that the type key can contain both the plural and singular name of the resource (people or person), and that it's the choice for the implementer which one to pick, it just needs to be consistent.

I'm wondering if there is a way to allow the JSON-API formatter to be configured, so that users can choose for themselves, with plural being the default. For example, I think I want to switch to singular :)

[groyoh]

Thanks for the feedback! :smile:

I did not noticed about the null/empty linkage. I'll try to work on it and see how it goes. And you made a little mistake, the json should be:

{
  "type": "post",
  "relationships": {
    "author": { 
      "data": null
    }
  }
}

For the type, I already thought about it a few times but I did not come up with a solution yet. If you have any suggestions, let me know. One other thing where I'm not really sure if it is or can be handled are the "self" and "related" urls of a relationship.

[groyoh]

@plexus @janko-m I need your feeback on this. In order to build self and related urls, should we add some new options to the associations/links or should we use something like this:

class PostMapper < Yaks::Mapper
  link "relationships.user.self", template: "whatever"
  has_one :user
end

[plexus]

Sorry for the slow reply, days are pretty full. I'll get back to you probably tomorrow.

[groyoh]

@plexus No problem :wink:

[janko]

Yeah, I don't really use links, so I don't have the feeling for what option is better. I'm currently on a long programless holiday, I won't really be available to review PRs for some time now, so don't wait for me ;). I wish you luck with this PR, it's great that you're doing this.

[groyoh]

@janko-m Enjoy your holidays then! :tropical_drink:

[plexus]

@plexus @janko-m I need your feeback on this. In order to build self and related urls, should we add some new options to the associations/links or should we use something like this:

class PostMapper < Yaks::Mapper
  link "relationships.user.self", template: "whatever"
  has_one :user
end

My first reaction would be that the user links would be part of rendering the user.

class PostMapper < Yaks::Mapper
  has_one :user
end
class UserMapper < Yaks::Mapper
  link :self, '...'
end

It seems JSON-API expects the self link to change depending on what top-level object you're including it from. I'm not sure I see the use case for that, but I can think of a couple ways to do that, for example.

class PostMapper < Yaks::Mapper
  has_one :user, mapper: Class.new(UserMapper) { link :self, ... }
end

[plexus]

Looks good :ok_hand: . I'm gonna merge it, we can take the discussion about the related object links to a separate issue.