Relationships, "self" and "related"

1

Hi,

in the docs there is an example for the JSON representation of a resource with a relationship.

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

I am wondering what the reasoning is behind linking to two sources in the “links” section. What do you expect to get when you either fetch http://example.com/articles/1/relationships/author or http://example.com/articles/1/author?

2

You expect to get the people resource id=9.

The self link within the relationship is the URL which identifies the relationship on the root resource. That relationship is the author of the article. The related link is the canonical URL for the author of the article.

Acting on the self link is an operation on the relationship between the article and the people resources. Acting on the related link is an operation on the related people resource itself.

The URL structures are of course entirely unnecessary, but are meant to help understand the distinction between these links.

I hope this helps!