Is it valid to exclude relationships from a relationships object?


#1

I have a resource that contains a lot of has-many “children” resources. I don’t want to include all of the relationships, only one specific (important) relationship (the “parent”).

{
  "data": {
    "type": "thing",
    "id": "1",
    "relationships": {
      "parent": { "data": { "type": "thing", "id": "9" } },
      "children": {
        "data": [
          { "type": "thing", "id": "1" },
          { "type": "thing", "id": "2" },
          { "type": "thing", "id": "3" },
          { "type": "thing", "id": "4" },
          // ...and so on
        ]
      }
    }
  }
}

Is it valid to create a relationships object that only contains some of the relationships? I’d like to be able to return something like this:

{
  "data": {
    "type": "thing",
    "id": "1",
    "relationships": {
      "parent": { "data": { "type": "thing", "id": "9" } }
    }
  }
}

Is that valid, even though it does not mention all of the known relationship types? Or do I need to change anything in the way that I request this structure (include params, etc)? Or can I return it this way by default?


#2

JSON API is (by my reading) a bit vague about whether it’s ok for the server to remove a relationship entirely without the client requesting that it be removed. Doing that might be allowed if, e.g. for permissions reasons, the client really shouldn’t be able to see a certain relationship, but I think it’s better to return a consistent list of relationships if possible.

So, with that in mind, there are two options that are definitely compliant:

  1. The client can explicitly ask to only get the parent relationship using the fields parameter).

  2. The server can include the children relationship, but only provide limited information about it. For example, if the concern is about sending unnecessary data, its perfectly valid for the server to send the children relationship like this:

"children": { 
  "links": { 
    "self": "http://example.com/thing/1/relationships/children"
  }
}

Then, the client can use the self link to fetch a list of the type–id pairs in the relationship. I think this is the option you want.

If you really can’t provide any links, JSON API even allows the relationship to be represented as:

"children": { "meta": {} }

But this is obviously not very useful to the client, so I wouldn’t recommend it.