Differences between the links objects

1

Hi

Is there a difference between the link object which is nested in the top level and the one nested in the data object.?

I read the specifications and here are the parts I’m asking about:

For the top level:

The top-level links object MAY contain the following members:

self: the link that generated the current response document.

related: a related resource link when the primary data represents a resource relationship.
pagination links for the primary data.

For the data object:

In addition, a resource object MAY contain any of these top-level members:

..........
inks: a links object containing links related to the resource.
.........

.

2

The top-level links object contains links related to all of the primary data, which might be a single resource or a collection of resources.

Each resource-level links object contains links only related to that resource.

3

Does that mean that for example the ‘self’ link of a resource will go either:

  • in the top-level links object when returning a single resource and in the resource level links object when returning multiple resources
  • or is it possible to add the ‘self’ link to the resource level links of the single resource
  • or just duplicate
4

@dnperfors On a request that directly targets a single resource (like GET /articles/2), the top-level self link and the resource-level self link mean the same thing, so you can use either or both (though using the relationship level one is probably preferable, so that clients can always look for that link, whether the response contains one resource or a collection of resources).

Note that some requests that return single resources may have different top-level and relationship level self links. For example, when requesting a relationship URI like GET /articles/1/relationship/author: in that response, the top-level self link would be “/articles/1/relationship/author”, while the resource-level one would be the link directly to currently-related author (e.g. /people/3).