Json-api: Clarify the difference between fetching from a related resource URL and a relationship URL

[jfinkels]

In the Fetching Resources section, the example _implies_ that the request

GET /articles/1/author

yields the response

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

{
  "links": {
    "self": "http://example.com/articles/1/author"
  },
  "data": {
    "type": "people",
    "id": "12"
  }
}

In the Fetching Relationships section, the example implies that the request

GET /articles/1/links/author

yields the response

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

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

Are GET requests to these URLs intended to be identical (except for the self link)? What is the difference between the /articles/1/links/author and the /articles/1/author endpoints?

[dgeb]

The Fetching Resources section is all about fetching _resources_ not relationships.

The first example is prefaced by "And the following request fetches an article's author:"

It should not yield the response you've indicated, but rather the author resource as primary data.

This is explained in the definition of "related resource URL" - see http://jsonapi.org/format/#document-structure-resource-relationships

[jfinkels]

Okay. This was unclear to me because it is possible for a "link object" and a "resource object" to be identical, if the representation of the resource includes only the minimum required elements (id and type).

[dgeb]

Is there an example that makes this unclear to you? Knowing the distinction now, do you have a suggestion to clarify it for others?

[jfinkels]

I appreciate you taking the time to consider how best to convey this information!

I think an example showing the response on a request to a related resource URL would help clear this up. For example, "on a request to GET /articles/1/author the response would be ..." and "on a request to GET /people/1/articles the response would be ...", both in the _Fetching Resources_ section.

Or I might just add a reminder that says "the response when fetching from a related resource URL is a resource object, whereas the response when fetching from a relationship URL is a link object." I know these are stated in the _Document Structure_ section, but a reminder that appears physically closer to the _Fetching Data_ section might be helpful.

[dgeb]

Ok - thanks for the suggestions, @jfinkels! I'll reopen this as a reminder to add such a clarification.

[bintoro]

This is already explained, just not in the _Fetching Resources_ section.

If we're going to have a more detailed discussion on related resource URLs, then ideally it should address resource creation as well (#496). It's pretty obvious that if a (related) collection supports POST, a newly created resource MUST end up as part of that collection, i.e., it should become associated with the parent resource. Spelling this out might not be necessary, but it wouldn't hurt to at least say something about the POSTability of related resource URLs.

[tkellen]

I believe this has been resolved in the latest revision of specification. I would be very open to a PR if it is deemed that further clarification is still needed.

[arielpontes]

I still don't understand what the difference is. Plus, some of the links in this thread are dead. Can anybody point me to a response example for each endpoint? In the _Fetching Resources_ section I found examples of responses from endpoints with the format articles/1/relationships/author. For the format articles/1/author, the only example I found was for an article with a missing author, which really doesn't help illustrate the difference.

[dgeb]

@arielpontes A relationship URL (like articles/1/relationships/author) should return resource identifier objects while a related resource URL (like articles/1/author) should return full resource objects.

[arielpontes]

Thanks @dgeb , I get it now. Still I think an example would really help illustrate this.

[nickjuntilla]

@dgeb If there is always one author then why have a link for "articles/1/relationships/author" that does not contain the information? That doesn't seem useful.

Even if there is a list of authors at both endpoints "articles/1/relationships/authors" and "articles/1/authors" there is still a 1 to 1 relationship. The only difference seems to be that one contains more information about the authors? Is this true? How is this useful?

If the "related" link inside of relationships is always the "self" link without the word "relationships" in the path why do we need to explicitly state it each time?

Is there an example of when the "self" and "related" keys in the links section do not have this exact transformation of just adding the word "relationships" to the path?

[dgeb]

@nickjuntilla Although you are not required to support either type of endpoint, they each serve a distinct function.

A relationship endpoint is specific to _the relationship_. Metadata (e.g. timestamps) and links can be returned that are specific to the relationship. Furthermore, the relationship can be mutated or deleted without affecting the resources involved. For instance, an article's author could be changed or cleared via a request to a relationship endpoint.

On the other hand, related resource links provide access to the related resource objects themselves (not the relationship).

[nickjuntilla]

@dgeb Could the relationship endpoint be derived from resource relationship in the URL? That is if there is a articles/1/authors can it be assumed that there will always be a articles/1/relationships/authors? I can see the usefulness as far as updating without affecting the contents of those objects, but now I'm wondering why we have to explicitly state something that seems like it can be obviously implied or at most implied with a boolean as to it's existence.

[dgeb]

@nickjuntilla The base spec doesn't make any requirements of URLs - only recommendations. Furthermore, there's no requirement that any links at all be included by the server. However, doing so makes your API more discoverable.

[nickjuntilla]

@dgeb Thanks, that clears things up.