Dealing with tree-like data structures in JSON API - json

Question

Let's say we have several resources, that can exist by themselves or can be organized in a tree-like hierarchy. I called them roots, branches and leafs just for convenience. Now I want to retrieve leaf's data:
GET /leaf/1
Accept: application/vnd.api+json
which must return me something like this according to JSON API spec:
{
"data": [{
"type": "leaf",
"id": "1",
"title": "Leaf 1",
"links": {
"self": "http://example.com/leaf/1",
"branch": {
"self": "http://example.com/leaf/1/links/branch",
"related": "http://example.com/leaf/1/branch",
"linkage": { "type": "branch", "id": "5" }
},
"root": {
"self": "http://example.com/leaf/1/links/root",
"related": "http://example.com/leaf/1/root",
"linkage": { "type": "root", "id": "7" }
}
}
}],
"included": [{
"type": "branch",
"id": "5",
"title": "Branch 5",
"links": {
"self": "http://example.com/branch/5"
}
}, {
"type": "root",
"id": "7",
"title": "Root 7",
"links": {
"self": "http://example.com/root/7"
}
}]
}
From the response data I can't say that the data is hierarchical and it seems appropriate to change leaf's root:
PATCH /leaf/1
Content-Type: application/vnd.api+json
{
"data": {
"type": "leaf",
"id": 1,
"links": {
"root": {
"linkage": { "type": "root", "id": "3"}
}
}
}
}
Which is of course not possible because this leaf is connected to the branch and only then to the root, and changing the root in the schema below requires to have an id of this root's branch. Questions are:
How (if it's possible) to represent a hierarchy in the resource
representation to make it clear to an API user that the changing
relationships may require additional data?

Answer 1

The problem with your example is that you are viewing your data as leafs and branches, not separate objects.
REST is about managing entities. Try to look at REST URL as a name of the entity. Not some fancy tree pointer.
So, in your case PATCHing leafs is not possible like that. To change an entity you must use the same path you used to create it.

Answer 2

I know this answer is late, but I'm just leaving it here for others in the future.
I think the way to go is to replace the "branch" and "root" relationships with a single "parent" relationship that points to the parent node (which is of course on a branch under some root). Then, the parent relationship can be patched to any other node, without an inconsistency being introduced (since that was the problem before with someone patching root but not branch).
Then, if you still want to expose the root node, not just the direct parent, you could put this information in meta somewhere, you could add back a "root" relationship but not make it writeable (I.e. PATCH attempts would return 400/403), etc.