Hello @ethanresnick and @Sephen, I am trying to solve the same issue of providing templated links in a JSONAPI response. I have few follow-up questions/comments based on your discussion here.
- In the example provided by @ethanresnick, it says this:
// Templated links aren't defined in the base spec, // but you can put them in `meta`.
Does the spec actually prohibit URI templates as URL values in links objects?
I can think of one problem with including URI templates, which is that clients may not (and likely will not) expect to receive templated URIs as links and therefore may try to fetch them directly, missing the needed interpolation of the template.
On the other hand, I don’t see which part of the spec makes templated URIs as links invalid, so is it truly non-compliant to include them?
I find it somewhat more appealing to provide a URI template in the link rather than in the meta field, although I’d like to remain spec-compliant if possible.
-
@Sephen if you are willing to share, I’m curious what solution you ended up using for this issue.
-
It looks like there’s a needed correction to the key names within the relationshop objects’ links in the example (self → related).
Reading JSON:API — Latest Specification (v1.1), I see the following descriptions:
“self: a link for the relationship itself (a “relationship link”).”
“related: a related resource link”
Further, related resource link is defined as
A “related resource link” provides access to [resource objects] linked in a relationship. When fetched, the related resource object(s) are returned as the response’s primary data.
Decoding that for the example below, it seems like the links to the actual “articles,” “authors,” and “brands” resource objects should be the related links, not the self links.
Below I’ve updated the @ethanresnick’s example to change the “self” to “related” and also added the valid “self” links to be explicit.
{
"links": {
"self": "http://example.com/",
},
// Below, I used an object for data rather than an array,
// since that seemed simpler, but either is valid.
"data": {
// the type and id values here can be whatever you'd like,
// but JSON API requires every resource provide something.
"type": "entrypoint",
"id": "1",
"relationships": {
"articles": {
"links": {
// by the spec we are not obligated to have both "self" and "related"
// but i'm including them to show the difference
// reference: http://jsonapi.org/format/#document-resource-object-relationships
"self": "http://example.com/entrypoint/relationships/articles",
"related": "http://example.com/articles",
}
},
"authors": {
"links": {
// it might be more consistent to not have "entrypoint/" in this URL
// and do this instead:
// "self": "http://example.com/relationships/authors",
// but either way should be valid
"self": "http://example.com/entrypoint/relationships/authors",
"related": "http://example.com/authors",
}
},
"brands": {
"links": {
"self": "http://example.com/entrypoint/relationships/brands",
"related": "http://example.com/brands",
}
},
"search": {
// Templated links aren't defined in the base spec,
// but you can put them in `meta`.
"meta": {
"uri-template": "http://example.com/articles/search/{keyword}"
}
}
}
}
}