When to present relationships objects

#1

Hello,

I was looking at the spec but was not able to find answer to the following question, for example I have resource /articles that has relationship to comment.

Consider following request: GET /articles.

a)

{
  // ..
  "type": "articles",
  "id": "19370",
  "attributes": {
    "name": ""
  }
  // ..
}

b)

{
  // ..
  "type": "articles",
  "id": "19370",
  "attributes": {
    "name": ""
  },
  "relationships": {
    "comment": {}
  }
  // ..
}

c)

{
  // ..
  "type": "articles",
  "id": "19370",
  "attributes": {
    "name": ""
  },
  "relationships": {
    "comment": {
      "links": {
        "self": "/articles/19370/relationships/comment"
      }
    }
  }
  // ..
}

Should it return a) or b) or c) acording the specification?

Thank you.

#2

C.

Otherwise you can also provide the data member with the actual relationship data.

https://jsonapi.org/format/#document-resource-object-relationships

#3

Hi,

according to the spec, the type of answer depends on the parameters that you pass in the request.

A simple GET /articles should return the variant a)
While a GET /articles?include=comments could return b) or c) depending on how you decided to implement this. JSONAPI gives the developer the freedom to decide if he/she should include the entire related resource or just a link to it.

#4

Sorry, yes, you are correct. To get the actual comments resources you would need to ?include=comments. The data member I was mentioning are just relationship links to “attached” comments (else [] or null if there are no comments). Either way, I think you have to identify that relationships exist with the response, IMO anyway.

#5

For me it looks quite reasonable too to indentify about possible/existing relationships, but to include actual comments data or not depending on query params. Thanks for suggestions.

#6

@apiator, where does the spec say that GET /articles (without include) should return a)? I’m fairly sure it normally should return c) (as @panman82 originally said), because the client needs the relationship links so it knows where to directly fetch the related resource (or relationship data). (Also, the API is not explorable if relationships require explicit prior knowledge in order to discover and traverse them.)

(If you don’t have relationship links, then c) would include an empty relationship object, and you must exclude it; in that case, a) is correct.)

For clarity: IIRC, according to the spec, the only difference include makes is that the relationship data includes linkage and the related resources are included in the included part of the document. I can’t see it saying that without include, relationship links should not be included.

#7

@cmeeren you are totaly right and thank you for pointing it out. My understanding was somehow biased by my own opinion about how this should be done and I did a superficial lecture of the spec, at least for this aspect of fetching resources, which led me to the wrong conclusions.