How to interpret the include request parameter

1

I wonder how to interpret the include request parameter fully.

From the specs:

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.

The value of the include parameter MUST be a comma-separated (U+002C COMMA, “,”) list of relationship paths. A relationship path is a dot-separated (U+002E FULL-STOP, “.”) list of relationship names.

I would assume that if a server does not support the include request param or in case a client does not provide the include request param the server will return with default behaviour. This could returning non at or everything. This could also be different behaviour per endpoint.

In the case the server supports the include param what should be returned:

  • In case the client does not provide the include param? I would assume the default behaviour as there is no rule in the spec that says it MUST be provided.
  • In case the client provided=s the include param as ?include=. Should this mean that the client does not want any included data?

And further more should or can the server accept wildcards like ?include=publisher,publisher.country,author.*. Note the * behind author to indicate that all (sub) relationships of the author should be included.

1 Like
2

If a client does not provide an include parameter, the API designer / developer is free to return any depth or set of relationships they desire. If they client does use it, the server returns a related resource IFF it is in the includes parameter. I would reject includes=. with a 400, as it doesn’t specify a valid member name. I would suggest the better way to support no relationships would be to have an extension which supports the user of the Prefer header to restrict the current representation, or use spare field sets to select the root resource attributes and none of its relationships.

I haven’t ever seen reference to supporting a wildcard, and I would seriously hesitate to support it in an API or specification. I also think it violates the naming rules linked above, and would add a lot of complexity to consumer agents.

One other minor point to add, I’d discourage you from using the ‘endpoint’ terminology in favor of ‘resource’, because it very subtlety directs the conversation towards RPC.

Thoughts?

3

Hi Micael,
Thanks again for joining the conversation!

I think you have a fair point regarding the wildcard. So let’s forget about that one :slight_smile:

Regarding the include request param

  • If it is not provided I think we agree the API designer / developer is free to return any depth or set of relationships they desire
  • If it is provided (and the API supports it) the API should only return the related resources
  • But what to do if the parameter is provided but without value: ?include=
    You mentioned to reply with a 400 as it no valid member name?
    Could you elaborate on that?
    As this could indicate imo nicely that no includes are desired. Opposed to something like ?include=author where you only desire the author related resources.
    Maybe my initial question caused confusion as it contained a trailing . I dit not mean ?include=..

I’m asking this as I’m working on a library that would provide out-of-the-box support for the include request param, and I’m wondering which rules I can apply best.

Cheers,
Marcel

4

If you follow a few of the links from the point in the spec where the includes parameter is defined, what you’ll get is it has to be a comma separated list of valid member names, deep linked relationships. Member names are defined as one or more characters. The empty string violates this constraint.

I think it would be a good shorthand to suggest you want the resource without any additional related resources. However, on reading the spec the points above are my interpretation for better or worse on what the spec says to do.

Hope that helps!

5

Yes looking at it more carefully I think you mean this part:

The value of the include parameter MUST be a comma-separated (U+002C COMMA, “,”) list of relationship paths. A relationship path is a dot-separated (U+002E FULL-STOP, “.”) list of relationship names.

Which indeed states it MUST be a comma-separated list, suggesting it MAY not be an empty value.

I wonder if the JSON:API spec could provide a recommendation on this or maybe even clarifying this a bit in the spec itself.
As you seem to be the most active in replying questions here, do you know the spec is still maintained and who could say something about adding such a thing to the spec?

6

It’s a list of relationship paths which are dot separated names, which are defined as 1+ characters.

The spec is still being maintained and worked on, but there is issues with updating quickly because of the promise of backwards compatibility. The unfortunate side effect of non normative language, this is the second time this week it’s coming up lol, is that it adds ambiguity if you aren’t extremely careful. There is some of that in the spec at this time.

7

I also tried to reach out to maintainers (via Twitter) to see if they can add some clarity to the spec regarding this include param. Either in the formal spec or at least in the recommendation section.