In order to request resources related to other resources, a dot-separated path for each relationship name can be specified:
/articles/1?include=comments.author
Does this mean if you want the author of the article along with other resources related to him, you would have to write like so?
/articles/1?include=author.cities,author.likes,author.comments,author.friends
That seems a bit redundant, especially when the term is longer than author.
Is there a suggested leaner syntax?
I’m not sure what you mean by this. Are you saying that repeating author is annoying, and you’re wishing there was an option something like /articles/1?include=author[cities,likes,comments,friends]?
Yes, that syntax looks much better. I’ll use that. Thanks.
UPDATE: I did not decide to go with this. Read down the thread.
Note: My example is not compliant with the JSON API spec. I was just trying to understand what was irritating you.
To be compliant I think you would need to do something like this: /articles/1?include=author&fields[author]=cities,likes,comments,friends, see sparse fieldsets
Yes. That’s better. I think you might’ve just forgotten to replace fields with relationships:
/articles/1?include=author&relationships[author]=cities,likes,comments,friends
I suppose this allows for a robust definition relationships:
/articles/1?include=author,comments&relationships[author]=cities,likes,comments,friends&relationships[comments]=author
No, A resource object’s attributes and its relationships are collectively called its “fields”.
Hmm, the spec does say that. However, I imagine differentiating between when fields is referring to attributes v.s. relationships would be difficult for a server-side REST framework to rectify.
For example:
/articles/1?include=author&fields[author]=cities,likes,comments,friends
In this example, how would the receiver of this request know that I want all author.attributes as well as the four listed relationships?
If those are not fields on the attributes, one might expect to end up with an empty author.attributes object.
It wouldn’t.
You would.
If this is a genuine problem I’d question the resource model and approach, for example:
includes by default, and not relying on clients to request them? (Clients that don’t want full data can always use fields to suppress what they don’t want.)I appreciate your input. This discussion has helped me.
- Are resources nested too deeply?
I don’t think so. My understanding is that the value of JSON API’s lies in the ability to make complex requests in a single call.
- Should some relationships be promoted to attributes?
Often they should. Sometimes they should not.
For predictability, we’re using our resource types as an ORM, so attribute keys can only be omitted in the request, not added.
- Should the server be performing includes by default, and not relying on clients to request them?
Perhaps.
… (Clients that don’t want full data can always use fields to suppress what they don’t want.)
I still think there needs to be a way to distinguish when to suppress keys on the attributes v.s. the relationships. This might be something to revisit in the next version.
In order to be compliant with the JSON API spec, I may just use the verbose dot syntax for the time being:
/articles/1?include=author.cities,author.likes,author.comments,author.friends
Interesting. For me the value is in being a more structured / opinionated format than HAL, while still being flexible. The include feature is a bonus. If I my problem called for lots of complex requests, I’d probably try to collapse them into a single call using GraphQL rather than JSON API.
I imagine there are a lot of benefits for users and I think that’s great.
GraphQL requires a different server infrastructure, so that is not always an option.
In Yehuda Katz’s interview with The Changelog #189, he explains at 1:22:56 that he believes the core value of JSON API is to allow for complex requests using an existing REST server infrastructure.
One of JSONAPI’s strengths is that it is designed to be easy to automate with good tools.
Aesthetic concerns over how readable or writeable it is to humans tend to be far less important in practice than people think. It needs to be debuggable by humans, but that is a different standard.
“Leaner syntax” for the query string only matters when you’re hand-assembling queries, and that is not really the happy path. Whereas introducing a more complicated grammar that’s more compact makes it harder to make the automated tooling always do the right thing.