If I may, after doing some research on the subject myself, I came across this explanation of @dgeb in a (rather old) post on github:
A self link for a relationship is called the “relationship URL” and should return the relationship’s linkage data - i.e. the resource identifier object(s) associated with the relationship. Requests can also be sent to the relationship URL to modify the relationship.
A related link for a relationship is called the “related resource URL” and should return the resource(s) currently in the relationship.
Given that, you should use related in your links (e.g. “https://api.example.com/compliance/facilities”) to return full resource objects.
The way I interpret this, together with the specs, I would come to the following request/responses based on your example:
The self
link http://example.com/articles/1/relationships/author
will return:
{
"data": {
"type": "people",
"id": "9"
}
}
Whilst the related
link in that case should be http://example.com/articles/1/author
, which would return the entire resource object:
{
"data": {
"type": "people",
"id": "9",
"attributes": { .. },
"links": {
"self": "http://example.com/people/9"
}
}
}
Does that make sense?