Add alternative payload format (2)

[wiresio]

Rework of #168

resolves #16

---

Preview | Diff

[farshidtz]

Thanks. I think the content is fine, but it needs some more work:

• The example is not correct. totalItems is 10 and all those 10 are listed: so no next pages. There is still a nextLink with offset 1. Should there be a nextLink when there are no remaining pages? If yes, the offset should be 10. I think a better fix would be to set total to 12 and nextLink to /things?offset=10&limit=10 to be consistent with the other pagination examples (array format).
• The API endpoint should be /things, not /td
• Missing API spec for the new interaction. I think addition of the new uriVariable (?format=array|hydraCollection) on the existing pagination form would suffice.

Some editorial issues:

• The new paragraphs should be added at the end of Listing (before errors) as this is an alternative to pure array. The existing paragraph starting with "Serializing and returning the full list of TDs may be burdensome to servers. As such, servers should serialize incrementally and utilize protocol-specific mechanisms to respond in chunks...." should be moved to after the hydra collection.
• Missing hyrda references
• Code as italic text instead of using <code> tag or backquotes

[wiresio]

Thanks for the feedback @farshidtz ! I applied your comments and will need some help with:

• Add references
• "code" instead of "i"

Let's resolve it in today's meeting.

[farshidtz]

"members" -> "member" ?

[mmccool]

Needs some refinement. In particular, as discussed, it's troublesome to depend normatively on a CG document, and it's also a problem to just define an extension point (with hydra collections as examples) since that creates interop problems. We need a built-in normative way to do this, but can't just adopt the hydra ontology directly. So it was suggested that we resurrect the design we had discussed in #16 and which can be seen in the context history, see e.g. de02ff0#diff-94098f295e6c8f89beca5d1221bbaefaf5c410e17b1a6be3d5df9051b205f72f

[farshidtz]

Since we are not strictly following hydra anymore, why don't we use plural items instead of the single member?

https://github.com/wiresio/wot-discovery/blob/66284902a8892fdf9764900f75c51c21fe958f36/index.html#L1419-L1423

"totalItems": 12,
"member": [
	{ TD },
	9 other TDs...
],

to

"totalItems": 12,
"items": [
	{ TD },
	9 other TDs...
],

The following maps better:
totalItems -> items
totalMembers -> memberS

or simply:
total + items or
total + members

[wiresio]

Thanks for the comment!
Actually I'd like:
total + members
We should also check the context - I'm not sure whether I put it right.

[mmccool]

This perhaps should be td:Thing included from the td context, since in the intent is to return TDs (formatted as TDs) and not general RDF graphs.

[AndreaCimminoArriaga]

I have to review in detail the new context, but maybe it would be better to have a separate context with the pagination terms, and the range of the term members should point to td:Thing or any of the types defined in the discovery context. In this way this second context is totally optional and would point to the main one