Collections / List endpoints should return JSON-LD

[nickevansuk]

Use Case

Provide a pattern for listing resources while querying a resource collection.

Proposal

Use Hydra Collections, except instead of using the "member" property for the list of resources, use "item", as the term "member" has a specific meaning within the sport and physical activity sector, and item is consistent with the existing totalItems property.

Example

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "id": "http://api.example.com/an-issue/comments",
  "type": "Collection",
  "totalItems": 4980,
  "item": [
    ... a subset of the members of the Collection ...
  ],
  "view": {
    "id": "http://api.example.com/an-issue/comments?page=3",
    "type": "PartialCollectionView",
    "first": "/an-issue/comments?page=1",
    "previous": "/an-issue/comments?page=2",
    "next": "/an-issue/comments?page=4",
    "last": "/an-issue/comments?page=498"
  }
}

See also

• List endpoints should return JSON-LD openactive/open-booking-api#7

[civsiv]

Why item and not items? Feels like a plural for an array makes more sense?

[lukehesluke]

@nickevansuk this looks good to me. And the id and type fields are consistent with e.g. the modelling spec

[lukehesluke]

@civsiv it being singular would be consistent with e.g. activity in an Event, which can be either a single activity or array. Or subEvent

[house92]

But we use items for /v2/sessions, /v2/activities, etc. Shouldn't they all be consistent?

[nickevansuk]

Great! Yes good spot: all schema.org props are singular (see https://www.w3.org/wiki/WebSchemas/Singularity for rationale), the previous prototype was incorrect in this regard.