List endpoints should return JSON-LD

[ldodds]

The list endpoints currently return a JSON structure like this:

{
 "links": {
 },
"data": [
 ]
}

They should return a doc which:

• has a @context property
• has properties that are defined in the relevant spec
• follow best practices around modelling with JSON-LD

We might want to use an ItemList http://schema.org/ItemList

[nickevansuk]

Just checking on this, we'd previously had consensus that using JSON API links and data properties was the way forward here. Is this still the case?

The idea with the above was to include @context in the "data" property's items as with the RPDE feed (and is consistent with the "data" property semantics in RPDE)

[ldodds]

Yep, we agreed to use this style of paging, e.g. an array of responses and specific link relations to handle paging (next, previous, etc). But the goal is for all the API responses to be valid JSON-LD and for there to be a single context declared.

This is first time I've seen really looked at what we're using in terms of syntax, rather than commenting on general approach.

As another reference, Hydra defines a response as a collection, with members and a view with similar links.:

http://www.hydra-cg.com/spec/latest/core/#collections

Have previously suggested this for RPDE too: openactive/realtime-paged-data-exchange/issues/54

[nickevansuk]

Makes sense. Hydra is similar and quite nice too. Though they have a "members" array for their items, which is inconsistent with the naming of the "totalItems" property. Considering "members" has a very specific meaning in our sector, I propose we opt for "items" instead. Everything else looks very similar to the JSON API approach we'd previously discussed.

Also suggest we define totalItems as an int rather than a string as they have it, and promote absolute URLs as we've done elsewhere.

So example below:

{
  "@id": "http://api.example.com/an-issue/comments",
  "@type": "Collection",
  "totalItems": 4980,
  "view": {
    "@id": "http://api.example.com/an-issue/comments?page=3",
    "@type": "PartialCollectionView",
    "first": "http://api.example.com/an-issue/comments?page=1",
    "previous": "http://api.example.com/an-issue/comments?page=2",
    "next": "http://api.example.com/an-issue/comments?page=4",
    "last": "http://api.example.com/an-issue/comments?page=498"
  },
  "item": []
}