Always return "included" where "include" has been requested

[noetix]

#1230

One additional thing that may be worthwhile is reiterating that the included param must always be an array, and that an empty array should be returned when no additional resources are available to add to the response.

Open to feedback. :)

[ethanresnick]

This is great. Just so we're not repeating the clause "If an endpoint supports the include parameter and a client supplies it", maybe we can merge the paragraph you added with the one that follows?

Something like:

If an endpoint supports the include parameter and a client supplies it:

1. The server's response MUST be a [compound document] with an included key—even if that included key holds an empty array (because the requested relationships are empty).

2. This included section MUST NOT include [resource objects] not requested through the include parameter's value.

[noetix]

Opted to leave the second list item as-is.

Good call on the repetition.

[ethanresnick]

The server MUST respond with the included section of the [compound document] — even if

I realize I'm really nitpicking here, and it's probably more important to just get this merged, but something about the wording quoted above bothers me. Specifically, I think having an included section is part of what it means to be a compound document (i.e., you can't be a compound document without one).

Your wording seems to suggest, though, that the response is already a compound document, which it isn't until the included section is added. That's why, in my wording, I tried to say that the the response must be a compound document. Then, I added "with an included key"—even though that's technically redundant—just to maximize readability in case the full implications of "being a compound document" weren't obvious.

Can we stick with my wording for the first bullet, and then I'll get this merged?

[noetix]

@ethanresnick Agreed.

[ethanresnick]

Great. Merged!