Encoding Relationships

[lindyhopchris]

Hi,

Just wondering how relationship endpoints are meant to be encoded? The encoder interface doesn't seem to have a method for encoding relationships, and I can't find any mention in your wiki about it.

The example instance from the JSON-API spec would be:

GET /articles/1/relationships/author HTTP/1.1
Accept: application/vnd.api+json

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/author",
    "related": "/articles/1/author"
  },
  "data": {
    "type": "people",
    "id": "12"
  }
}

[neomerx]

Your links belongs not to the resource but to the document (side question for you what do you think it would belong to if data contains array of resources?).

Anyways you can add such links with a second parameter of encode method. For your case it will be

    $links = [
        'self' => new Link('/articles/1/relationships/author'),
        'related' => new Link('/articles/1/author'),
    ];

However most likely you want

• to have those links in resource relationships
• have them automatically generated

In this case you need to add them in Schema like here.

If you have any further questions please don't hesitate to ask.

[lindyhopchris]

The problem is the data member, not the links member. There's no way of passing in an object that has a type and id member, because the encoding process tries to look up a SchemaProvider for the object.

Effectively this endpoint is returning a Relationship Object that is in the root document. I've tried providing a Neomerx\JsonApi\Schema\RelationshipObject as the first parameter for encode, but it doesn't work because the encoding process tries to look up a SchemaProvider for it.

As there's an error and errors encoding method on the EncoderInterface, does there not also need to be a relationship method for encoding Relationship Objects directly to the document?

Also, would it not be possible for this to be done using the SchemaProvider? In the example above, effectively the endpoint is returning the author relationship that can be obtained by using the getRelationships method on the ArticleSchema object.

So effectively what you want to be able to do is something like this on the encoder interface:

public function relationship($resource, $relationship, $meta = null, EncodingParametersInterface $parameters = null)

which in the example would be called as:

$encoder->relationship($article, 'author');

[neomerx]

I admit I don't understand the question. After reading your original question a few more times I can't understand where it might come from.

My questions in particular

• what is a 'relationship endpoint'?
• why it should be encoded separately from object?
• what is a real life example of it (maybe this help)?

I think it will be easier to discuss in more interactive way with

[neomerx]

This post might be completely irrelevant to your question but what I think while reading you second comment

There's no way of passing in an object that has a type and id member, because the encoding process tries to look up a SchemaProvider for the object.

Encoder don't work with input data directly it uses Schema for that. You can program Schema for reading any properties from objects (named id and type as well). You can register Schema for any type including object (obviously no more than 1 Schema per PHP data type) but I don't understand why not using classes for that as they have stronger typing.

Effectively this endpoint is returning a Relationship Object that is in the root document.

I've got same set of questions what is this endpoint, what PHP type it has, why it should be encoded separately and how it fits JSON-API spec.

does there not also need to be a relationship method for encoding Relationship Objects directly to the document?

That's likely the same question applied to similar object Error. I don't understand the original idea about endpoint-relationship and how it fits the spec.

Also, would it not be possible for this to be done using the SchemaProvider?

A real example might help to understand what you want to achieve.

[lindyhopchris]

@neomerx It's been evening here (York, UK) and I've been out tonight!

Will be able to write more tomorrow if needed, but the endpoint I'm talking about is fully documented in the JSON API spec. See http://jsonapi.org/format/#fetching-relationships

A server MUST support fetching relationship data for every relationship URL provided as a self link as part of a relationship's links object.

A server MUST respond to a successful request to fetch a relationship with a 200 OK response.

The primary data in the response document MUST match the appropriate value for resource linkage, as described above for relationship objects.

That section of the spec has examples in it.

[neomerx]

I got it.

You have to add handler to your controller that reads author/comments from data storage and returns encoded result.

class ArticlesController
{
    public function getRelationship($articleId, $relationshipName)
    {
        ...
        $author = ...;

        $links = ???

        $this->getResponse($author, 200, $links);
    }
}

The question is what is the best way to create $links?

$author doesn't contain information about response links and that it actually come from a relation to Article. So Encoder can't add such links to output without additional data.

You know you're in Article controller handler for relationship requests so one option is to create such data manually

$links = [
    'self' => new Link("/articles/$articleId/relationships/$relationshipName"),
];

Another option is to automate Link process generation fully or partly. For such link generation we need

• Articles JSON-API type (from ArticleSchema)
• $articleId and $relationshipName (Controller parameters)

Thus such generation function might look like

createRelationshipLink(Article::class, $articleId, $relationshipName);

What are your thoughts on that?

[lindyhopchris]

I really feel this totally has to be automated, because otherwise I'm having to program a lot of logic into a controller that is actually contained within the relevant schema providers. It's a duplication of code, which means I'll have two places to update stuff.

For this request:

GET /articles/1/relationships/author HTTP/1.1
Accept: application/vnd.api+json

The minimum response is:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "people",
    "id": "12"
  }
}

(I've intentionally left out the links, as they are not compulsory whereas the data is.)

In the controller, I get the article from the data store, and then get the author from that. I now have to construct a resource identifier for the response, for which I need to know in the controller that the type of $author is people. To work that out without hard coding it into my controller, I need to get the schema provider out of your container.

Also, if I'm using a single instance of an Encoder across my whole application, the other thing I'll need to do in the controller is return a response that is encoded consistently with every other endpoint in the API. That information is held in the EncoderOptions that the Encoder is created with. So therefore it definitely makes sense to me to use the encoder to generate the JSON response.

So the result of this, is I need the encoder to generate the entire JSON response, both data and links.

Another thing is the spec says that the response at this endpoint needs to match the relationship object contained within the resource object to which it relates.

The primary data in the response document MUST match the appropriate value for resource linkage, as described above for relationship objects.

So if my article resource object looks like this:

{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "/articles/1/relationships/author",
        "related": "/articles/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  }
}

Then the response to the /articles/1/relationships/author endpoint must match the value in the above JSON at /data/relationships/author. That means that the ArticleSchema class already knows how to generate that, because if you call getRelationships on that schema it's the author key in the returned array.

So all I need to do in the controller is get the article based on the id, then asked the encoder to encode the author relationship for the supplied article. The schema provider for article already knows how to get the author from the article because that's written into the getRelationships method, and it knows what the links are because they are also written into that method.

[neomerx]

I've got an idea to split this task into 2 parts

• first one is adding a helper for adding links to document
• the second is adding support for encoding relationship of a given object (which will be using the first part)

I've added a non-working prototype (feature/issue55 branch) for the first part (needs small changes in Encoder). Please have a look if we are on the same page. Possible usage might look like

$encoder = ...;
$encoder->withRelationshipLink(
    DocumentInterface::KEYWORD_SELF,
    Article::class, 
    $articleId,
    $relationshipName
)->encode(...);

the code itself

Yes, I would appreciate your help with it. I'm working on CORS support at the moment (which might be useful for you as well).