Description
IMHO, the terminology of relationship specification is a bit confusing. URLs are provided for the relationship itself and for the resources referred to via the relationship, but there is no way to provide a direct URL of the resource being referred to (i.e., its self), the user has to construct it from the type/id or make a call to related and get self from it. IMHO, it is an unnecessary limitation, especially for APIs which do not support compound documents.
I know that similar things were discussed (e.g., in #312 & #392), so I apologize if I am reintroducing something which has already been decided upon, but I do not think this particular suggestion has been discussed.
I think it would be good to straighten up terminology and provide way to specify URLs for all 3 types of references. So we would have
- "self": relationship itself,
- "related": reference to the target object of the relationship through the relationship,
- "target": direct reference to the target object.
Proposal: each individual linkage item, for both to-one and to-many relationships, must contain at least on of the following:
- a combination of
typeandidmembers, - a direct URL of the resource being linked as a member
target.
An example to illustrate all possible combinations (obviously, any given API is not expected to mix them all, at least not in one relationship):
{
"type": "articles",
"id": "1",
"title": "Rails is Omakase",
"links": {
"self": "http://example.com/articles/1",
"author": {
"self": "http://example.com/articles/1/links/author",
"related": "http://example.com/articles/1/author",
"linkage": { "type": "people", "id": "9" }
},
"editor": {
"self": "http://example.com/articles/1/links/editor",
"related": "http://example.com/articles/1/editor",
"linkage": { "target": "http://example.com/people/10" }
},
"proofreader": {
"self": "http://example.com/articles/1/links/proofreader",
"related": "http://example.com/articles/1/proofreader",
"linkage": { "type": "people", "id": "11", "target": "http://example.com/people/11" }
},
"illustrators": {
"self": "http://example.com/articles/1/links/illustrators",
"related": "http://example.com/articles/1/illustrators",
"linkage": [
{ "type": "people", "id": "12", "target": "http://example.com/people/12" },
{ "target": "http://example.com/people/13" },
{ "type": "people", "id": "14" }
]
}
}
}