Add alternative payload format

[wiresio]

Base for discussion about introducing an alternative payload format allowing to send pagination info in body.

• Close allignment w/ Hydra (e.g. usage of context) - yes/no?
• Description sufficient?
• References to be fixed

---

Preview | Diff

[mmccool]

Discussion:

1. This still needs chunking/framing, so would be in addition to that.
2. Pagination can still be done simply with appropriate queries, and an example for that would be helpful.
3. Returning different content types from a single interaction will complicate the scripting usage - perhaps a different interaction would be better. This would remove any potential issues with use of content negotiation with scripting, in different protocols, etc.
4. This complicates implementation - could it be optional? But then consumers can't depend on it. If it was a separate interaction that was not required, then if it was not in the TD, then a consumer would not be able to use it.

[wiresio]

1. Yes, would be in addition. Chunking anyway is optional.
2. Yes, however downloading all TDs incl. pagination from the TDD should be explicitly available (via listing) and not just implicitly (via search).
3. What about adding another query parameter for this, like ?pagination=inband/outband? Content negotiation will not help since both responses have contentType as "application/ld+json".
4. Could be optional such that only one reference implementation has to support it. Consumers can depend on the "pure" listing API and might access an optional "convenience" listing API.

[farshidtz]

What about adding another query parameter for this, like ?pagination=inband/outband? Content negotiation will not help since both responses have contentType as "application/ld+json".

The hydra spec does use application/ld+json in examples but it doesn't recommend or mandate it as far as I looked. The hydra spec itself is an unofficial draft. I think something like application/vnd.hydra+json would work.

Alternatively, similar to what you suggested, adding a query parameter such as ?hydraCollection[=true] could be used to override the default. Or ?format=array|hydraCollection if we want to make it extensible.

[mmccool]

Discussion (12 July):

• Needs to be updated to match latest spec
• No strong objections, especially if it is just another way of doing things
• Regarding mandatory vs. optional; still need two implementations even for optional features; however, consensus is to make it optional
• Need to clarify when to use the "envelope" vs. using "listing" (perhaps some text to explain when each is appropriate; can be added to this PR).

[mmccool]

Replaced with new PR, will close this one without merging.