Adding Links to resources and included

[kasperhelweg]

How can one add links to a resource object such as

{
    "data": {
        "type": "leads",
        "id": "29",
        "attributes": {
            "status": 0
        },
        "links": {
            "self": "localhost:4000\/leads\/29",
            "somelink": "link"
        }
    }
}

where "somelink" is the link to be added? Thanks!

[neomerx]

Wiki
Code example

For your case it would look like

...
    'somelink' => new Link('link')
...

[neomerx]

Have I answered you question?

[kasperhelweg]

Thanks for your reply. I get

Call to undefined method MySchema::linkAddTo()

[neomerx]

Oh yeah. Sorry for incorrect example. Tests have it's own special 'development' version of schema. I'll update 'normal' example in a few minutes.

[kasperhelweg]

Thanks!

[neomerx]

Example

which produces

{
    "data": {
        "type": "sites",
        "id": "1",
        "attributes": {
            "name": "JSON API Samples"
        },
        "relationships": {
            "posts": {
                "data": [
                    {
                        "type": "posts",
                        "id": "321"
                    }
                ],
                "links": {
                    "some-sublink": "http://example.com/sites/1/resource-sublink",
                    "external-link": "www.example.com"
                }
            }
        },
        "links": {
            "self": "http:\/\/example.com\/sites\/1"
        }
    },
    "included": [
        ...
    ]
}

[neomerx]

Is good now?

[kasperhelweg]

Is it on purpose that links can only be added to the links of a relationship resource object? What I'm looking for is adding a link to the primary resource-objects links object. In your example that would be the links object containing

"self": "http:\/\/example.com\/sites\/1"

But maybe the link objects are not supposed to be used like that? Are they restricted to having only a self link and a related link?

[neomerx]

links could be added to the resource as well

[neomerx]

@kasperhelweg Does it work for you?

[kasperhelweg]

Yes, it works. Thanks. One final question: how would I have the links for a resource appear in included if that resource is included? Is there a way to add links to included object? There is a

protected $isShowSelfInIncluded = true;

that will show self links. But can I add other links to those objects?

[neomerx]

Do you mean to show/hide some relationship links depending on whether object is a main resource or included resource?

[kasperhelweg]

If for example I have a resource that that looks like this

"data": {
    "type": "leads",
    "id": "29",
    "attributes": {
        "status": 0
    },
    "relationships": {
         ....
    },
    "links": {
        "self": "localhost:4000\/leads\/29",
        "other-link": "other-link"
    }
}

and I include that with another resoruce

{
    ...,
    "included": [{
        "type": "leads",
        "id": "29",
        "attributes": {
            "status": 0
        },
        "relationships": {
            ....
        },
        "links": {
            "self": "localhost:4000\/leads\/29",
            "other-link": "other-link"
        }
    }]
}

[kasperhelweg]

But I can only see that I can set

$isShowSelfInIncluded = true;

which will include the self link but not other-link

[neomerx]

I haven't thought about such a scenario 😄
You can do it with a schema that behaves differently depending on main resource encoded

Naive approach

        $encoder  = Encoder::instance([
            Author::class  => AuthorSchema::class,
            Comment::class => CommentSchemaWithoutLinks::class,
        ]);

        echo $encoder->encode($author) . PHP_EOL;

// and with links for comments when main resource

        $encoder  = Encoder::instance([
            Author::class  => AuthorSchema::class,
            Comment::class => CommentSchemaWithLinks::class,
        ]);

        echo $encoder->encode($comment) . PHP_EOL;

Better approach

Schema could act dynamically when created with Closure. And example of that could be found here

So for your question it might be something like

        $addLinksInComments = true;
        $schemaClosure = function ($factory, $container) use (&$addLinksInComments) {
            $schema = new CommentSchema($factory, $container, $addLinksInComments);
            return $schema;
        };
        $encoder  = Encoder::instance([
            Author::class  => AuthorSchema::class,
            Comment::class => $schemaClosure,
        ]);

        echo $encoder->encode($author) . PHP_EOL;

CommentSchema should act accordingly to value in $addLinksInComments

UPD Actually this feature a is used in tests very actively. In the code example I gave earlier you can see it in action.

[neomerx]

This feature might look as non-trivial. Are you OK with it or need some help?

[kasperhelweg]

Well, I'm not sure exactly what the example does 😃 My problem is that I can't figure out how to define links in a schema in general. For example, when extending SchemaProvider I can overwrite getAttributes( ) and getRelationships( ) which works really well. I'm looking for something like a getLinks( ) method that I can overwrite. Does that make sense?

[kasperhelweg]

I can add links to a top-level object by doing $encoder->encode($resource, $links, $meta) and I can add links to the relationships of an object by overwriting getRelationships( ). But I just can't figure out how to define links for a resource in general.

[neomerx]

You can't (maybe yet, I don't think it's difficult to add). Do you want Schema to have top level links that will be added to document on encoding?

[kasperhelweg]

Yes, something like that... If it makes sense to have that 😄

[neomerx]

I will create a branch and we can work on your questions. As far as I understand you've got 2 issues

• Ability to set some default links that will be added to top level links when resource is encoded as main resource (Enhancement)
• A working example with a Schema that could be managed. E.g. $commentSchema->setIncludeLinks(bool) and depending on that value links will be added/hidden

[kasperhelweg]

But if the main resource-representation contains a number of links, I guess it would make sense that those links could also be included if that resource is included with another resource? Just like all the relationships can currently be included with an included resource.

[kasperhelweg]

That would be cool! Yes, those are my issues 😄

[neomerx]

@kasperhelweg I've found even easier way to do that. Check out this sample which addresses your second issue. It corresponds with this code in Schema.

Full commit code

[neomerx]

@kasperhelweg With default top level links taken from schema there is a problem. What if encoded data is array? Should links be added and if yes which ones, first resource's or from all resources?

[neomerx]

I'm afraid the only reasonable way to add these links is to pass them to Encoder on encoding. What are your thoughts on that?

[kasperhelweg]

Cool. Just to be clear that we are on the same page 😄 , if I do

GET /comments/1
{
    "data": {
        "type": "comments",
        "id": "1",
        "attributes": {
            ....
        },
    "links": {
        "self": "/comments/1",
        "other-link": "other-link"
    }
}

would be a primary resource representation. I can easily do this by $encoder->encode($comment, $links) where $links contains the links. Now if I do

GET /posts/1

I would expect to get the exact same representation in the included section. Like this

{
    "data": {
        "type": "posts",
        "id": "1",
        "attributes": {
            ....
        },
        "relationships": {
            "comment": {
                "data": {
                    "type": "comments",
                    "id": "1"
                }
            }
        },
        "links": {
            "self": "/posts/1",
        }
    },
    "included": [
        {
            "type": "comments",
            "id": "1"
            "attributes": {
                ....
            },
            "links": {
                "self": "/comments/1",
                "other-link": "other-link"
            }
        }
    ]
}

The problem is that I can't easily do $encoder->encode($post, $links) because the links would be added to the posts object.

What I imagine is that there is simply a getLinks( ) method in SchemaProvider that I can overwrite just like getAttributes( ). Then, there might be a bool protected $isShowLinksInIncluded that can be set on the Schema and if true, would return links like above.

I would gladly help working on this at some point.

[kasperhelweg]

Alternatively, maybe I could pass the links to the encoder but something like

$encoder->encode($post, $links)

where

$links  = [ 'post' => [ Link::SELF => new Link('/posts/1') ], 'comment' => [ .... ] ];

not sure if that makes sense at all...

[neomerx]

I think you mess a bit with links. In your first example link will be added to document level but not to comment (very easy to miss).

[neomerx]

it will look like this

{
    "links" : {
        "link-as-param-to-encode" : "/could/be/anything"
    },
    "data" : {
        "type"       : "people",
        "id"         : "9",
        "attributes" : {
            "first_name" : "Dan",
            "last_name"  : "Gebhardt"
        },
        "links" : {
            "self" : "http://example.com/people/9"
        }
    }
}

See? You have links at document level and in resource.

[kasperhelweg]

Oh, you'r right.

[neomerx]

OK, wrap it up.

We have solved issue with dynamic Schema, haven't we?
We found out that document top level links looks as most reasonable solution. Having them in Schema appeared interesting from the first look but it causes issues when resources are arrayed. Agreed?

Anything left unanswered?

[kasperhelweg]

Nope, that's all good! Thanks for the effort!!

[neomerx]

Super. Don't forget to support the project with ⭐ 😉

[kasperhelweg]

I will!

[yoanisgil]

I have a somewhat similar situation:

{
  "data": [
    {
      "type": "domain",
      "id": "example.org",
      "attributes": {
        "name": "example.org",
        "ipV4Address": "1.1.1.1"
      },

    },
    {
      "type": "domain",
      "id": "as.com",
      "attributes": {
        "name": "as.com",
        "ipV4Address": "1.1.1.2"
      }
    }
  ]
}

and I'd like to include a links object for each resource of type domain. $encoder->withLinks won't work since it will added at the top level, and relationships seems a bit overkill. Below what I would like to achieve:

{
  "data": [
    {
      "type": "domain",
      "id": "example.org",
      "attributes": {
        "name": "example.org",
        "ipV4Address": "1.1.1.1"
      },
      "links": {
          "configuration": "/domains/example.org/configuration" 
      }
    },
    {
      "type": "domain",
      "id": "as.com",
      "attributes": {
        "name": "as.com",
        "ipV4Address": "1.1.1.2"
      },
      "links": {
          "configuration": "/domains/as.com/configuration" 
      }
    }
  ]
}

NOTE: I just want to know if something like this is easily doable, if not I think it will have to go for a relationships entry for each resource.

[yoanisgil]

Now that I think about it I don't really want to use relationships since I will be forced to resolve DNS records for the given domain and that's just to costly. I would really like to provide a link for an endpoint providing that information, should the client ever need to retrieve it.

[neomerx]

@yoanisgil it seems the lib restricts links to 'self' only on resource level. I've looked to the spec and there is no such restriction (likely it was in earlier revisions). It could be an enhancement/bug.

If you still want to add links despite your DNS issues you can use relationships. I don't see any real difference to have those links on resource level or relationship level.

Anyways thanks for spotting this issue. I'll create an enhancement for it.

[yoanisgil]

Not a problem. The issue with relationships is that I don't really want to return DNS records because I will be forced to resolve them which is a rather expensive operation. That's why I just want to provide a link to an endpoint providing such information.