JSONAPI resource relation urls

[lsylvester]

Currently, the jsonapi adapter adds resource relationships as link objects with ids and types. The jsonapi spec also allows the the resource relationship to be defined as a URL (see http://jsonapi.org/format/#document-structure-resource-relationships). For example:

{
  "type": "articles",
  "id": "1",
  "links": {
    "comments": "http://example.com/articles/1/comments"
  }
}

There is currently no way to do this using ActiveModel::Serializers as far as I can tell.

I propose that there should be a :url option for the assoications methods has_many and belongs_to that can be used to generate an resource url instead of linked objects, so that the above resource could be generated by the following serializer:

class ArticleSerializer
  has_many :comments, url: [:article, :comments]
end

I am not sure if this option is useful for the other serializers, so feedback on this would be appreciated.

If you are happy with this suggestion I can work on the implementation for this.

[joaomdmoura]

It seems a good proposal but I'm not so sure how many of AMS users are using this pattern.
About the implementation itself it think there is no need for [:article, :comment].URL might be just a flag.

Ex.

class ArticleSerializer
  has_many :comments, url: true
end

But would be cool to hear more thoughts about it. btw keep up the good work! 😄

[lsylvester]

So the url would be generated by something along the lines of url_for(object, association_name).

That works for me.

[lsylvester]

The spec also allows this url to be embedded in the link object instead of replacing the link object with a url, so the original example would become:

{
  "type": "articles",
  "id": "1",
  "links": {
    "comments": {
       "related": "http://example.com/articles/1/comments"
     }
  }
}

In this format, it can optionally be combined with the currently used linkage.

I think that it would be better to implement support for this format than the original suggestion.

From a api point of view, I think that it would make sense to use the :embed option to describe what members to put into the link object, so the :embed options for the jsonapi adapter could be :linkage, :related_uri and :self_uri, or an array of any combination of these, with the default being :linkage

[krzkrzkrz]

Any updates on this? In the meantime, is there a workaround we can use to get the links feature going?

Btw, @joaomdmoura links is part of the jsonapi spec: http://jsonapi.org/format/#document-links

[joaomdmoura]

@krzkrzkrz not yet, there is a pagination link PR going on but not this one yet.
But I still think that this is necessary and a valid proposal.
It's in out radar, I would be willing to review a PR, otherwise I'll work on it once I finish some new features I've being working on focused on deserialization (that will be also awesome to JSON API 😄)

[lsylvester]

The jsonapi spec has been updated since the initial proposal.

The relationships can now look like:

{
  "links": {
    "self": "...",
    "related": "..."
  },
  "data": [],
  "meta": {}
}

I think that to represent this in a serializer, it could be like

has_many :comments, data: true, links: {self: true, related: true}

In order to include a query param in the link (for example for pagination), you could set the value of the link object to a hash, like:

has_many :comments, data: false, links: {first: {page: '1'}}

Or a custom url could be used by passing in an array or proc as the value in order to generate a different url to the default one for if the url structure doesn't match the default behaviour.

has_many :comments, data: false, links: {self: [:article, :relationships, :comments], related: -> object { custom_path(object) } }

I am happy to work on a PR once I know the desired format to define the links for relationships.

[joaomdmoura]

Hey @lsylvester, tks for point out the change on relationship proposal.
But I'm not sure about the format proposals.
I wouldn't worry about pagination yet, and maybe we could make link a boolean

has_many :comments, links: true

• data default value would be true
• links default value would be false

How do you feel about it?

[SeyZ]

👍

[SeyZ]

Hey guys, I repeat the @krzkrzkrz question:

In the meantime, is there a workaround we can use to get the links feature going?

[joaomdmoura]

so @SeyZ and @krzkrzkrz you could try to workaround this by creating a new adapter that inherits from json-api's one but it is almost implement the feature itself.
I can't thing on a easy workaround on this that would still follow the json-api conventions. 😢