-
Notifications
You must be signed in to change notification settings - Fork 890
Closed
Description
Here's what I'm proposing. Instead of resource objects looking like:
{
attributes: {...}
links: {
self: "",
tags: {...}
}
}
We'd have:
{
attributes: {...},
links: {
self: ""
},
relationships: {
tags: {...}
}
}
That is, the self link would go in a separate "links"
object, and everything currently in the resource-level "links"
would go in a new container (re)named "relationships"
. ("tags"
is just an example relationship in the code sample above.)
There were two things motivating this proposal:
- Extensibility of resource-level
"links"
. It's quite likely that we may want to add other"links"
in the future, and we can't do this post 1.0 if"links"
and relationships share a namespace. Even pre 1.0, we can't do this without putting further restrictions on the name of a user's relationships, which I don't think we want to do. As examples of keys we might want to add to resource-level"links"
, consider:"collection"
(the url for the collection the resource is from),"latest-version"
,"alternate"
, etc. all of which are standard link-relation names that could be quite useful. I'm also thinking about how we set ourselves up to be able to implement web linking later if a common json format for it ever arises, and having a separate property bag where every official relation name is a valid key, and where the value is always a url, seems like a prerequisite. - Clarity, in a few different senses. First, the spec talks about "relationships" and "related resources", so having this terminology reflected in the json (much like we did for attributes), would make the spec easier to follow. Second, the
"self"
link really does seem to be a different kind of thing from a relationship, in that it can't have linkage and that a request to, e.g./people/1/links/self
doesn't make sense, so putting it in a different container also seems appropriate. Moreover, we'd get consistency between the format of the"links"
object at the resource level and the top-level. (Shout out to @bintoro for making most of these points about terminology in Rename top-level 'links' & clarify what a link is #380. The key difference between my proposal and the discussion there is that I'm proposing to have the relationships and the links into two separate objects, where as the prior discussion left them in the same object but debated that object's name.)
Here are the effects that my proposal would have on terminology:
- The object holding the relationships be called the "relationships" object. Each "link object" it contains would become a "relationship object". The resource-level
"links"
object, which still exists, would continue to be referred to as such. - Totally optionally, the
"linkage"
key could be renamed the"content"
key (as in "the content of the relationship"), now that the parent key isn't called"links"
. If this were done, a "linkage object" could then become a "resource identifier object", which is actually a better name because we use this form of object for things like bulk deletion too, in the"bulk"
extension.
Metadata
Metadata
Assignees
Labels
No labels