If an endpoint supports the include parameter and a client supplies it, the server MUST NOT include unrequested resource objects in the included section of the compound document.
An endpoint supports the include parameter.
By default, it returns all resources in the included section.
How can I avoid getting any resources in the included section at all?
Hi Oskar
If the endpoint supports the include parameter it should not return all resources in included section and only include resources specified in parameters.
If the default behavior is to include some relationships, but for a given request you’d rather have none included, you could simply provide an empty include parameter like //api.example.com/resources?include=
Is this specified somewhere in the documentation?
Thank you, that is what I was thinking too. I am still interested in Joana’s answer though, it would be the preferable method for me, if documented somewhere.
Hi Oskar,
My answer was extracted from:
http://jsonapi.org/format/#fetching-includes
An endpoint MAY also support an include request parameter to allow the client to customize which related resources should be returned.
...
If an endpoint supports the include parameter and a client supplies it, the server MUST NOT include unrequested resource objects in the included section of the compound document.
This seems very clear to me…
It seems like that is restricted to a scenario when both the endpoint and client supplies the include parameter, not when only the endpoint does it. Do you agree?
Please note that is clear on same topic (http://jsonapi.org/format/#fetching-includes) that if include parameter is not supported by server it may not be sent by client, because server MUST respond with 404.
If a server is unable to identify a relationship path or does not support inclusion of resources from a path, it MUST respond with 400 Bad Request.
So, my understanding is that this is very clear, because client may only send include parameter if server supports it, and if server supports include than server can only send the resources requested to be included…
I want to agree, but I can’t.
If a server is unable to identify a relationship path or does not support inclusion of resources from a path, it MUST respond with 400 Bad Request.
This only says that it must respond with 400 Bad Request if the client asks for something that doesn’t exist or is not supported. It does not have anything to do with whether the endpoint should give included resources by default or not.
From what I have read and understood so far, there are no documented rules or conventions concerning this situation.
The problem with not including all relations by default is that it creates a different result from an endpoint that does not support the include parameter. I can see how this would be an inconvenience for people using different APIs following the JSON API standard, and I think that trumps the more “common sense” approach of returning no included resources by default.
But something in the documentation about this would be useful, nevertheless.
I definitely agree that standard should be more clear on this (and in a lot of other things), there’s lot of space for interpretation which is not good for a standard.
Anyway… my deduction was from the part of the sentence that says or does not support inclusion of resources, to me this means that if server doesn’t support include parameter it should respond 404.
Major problem is that there are a lot of MAYon the standard allowing different server implementations, so clients cannot assume that all servers will have same behaviour:
An endpoint MAY return resources related to the primary data by default.
An endpoint MAY also support an include request parameter to allow the client to customize which related resources should be returned.
I don’t see that this follows. If a server does not support the include parameter, it is not required to return a compound document; it could respond with a resource object with relationships, which would mean clients would have to make multiple calls to retrieve all the data.
Or am I misunderstanding your point?
No, I think you’re right. Thanks for clearing that up!