JSON-LD links for pagination

[spyysalo]

The Eve "HATEOAS" _links field generation is currently switched off, making the (mandatory?) _meta fields the only piece of information available regarding pagination:

  "_meta": {
    "max_results": 25,
    "page": 1,
    "total": 13580
  }

This should be removed from the collection GET response and replaced with proper JSON-LD links. These could perhaps be easiest to make by rewriting the Eve HATEOAS _links.

[juanmirocks]

Can you paste here a sample of the JSON-LD links/pages ? -- As a first thought, I would rather write a wrapper of the EVE calls and do the necessary changes in the JSON output to get the right link objects.

[spyysalo]

Sure! First, the pagination _links that Eve generates with HATEOAS=True look like so:

  "_links": {
    "last": { "href": "annotations?page=544", "title": "last page" },
    "next": { "href": "annotations?page=2", "title": "next page" },
    "parent": { "href": "/", "title": "home" },
    "self": { "href": "annotations", "title": "annotations" }
  }

Now, as far as I can tell, there are no established standard URIs for pagination controls, but just using some for the basic link relations (next, prev etc.) should do to get started (see also https://github.com/restful-open-annotation/spec/issues/1). So, if we were to have definitions like e.g.

  "lrel" :  "http://www.iana.org/assignments/link-relations/#",
  "next":   { "@type": "@id", "@id": "lrel:next" },
  ...

in the JSON-LD @context, the pagination links could simply look like this, in the top-level @graph:

    "last": "/annotations?page=544",
    "next": "/annotations?page=2",

Some notes:

• This suggestion drops Eve self as redundant, as we already have this by definition in the JSON-LD @id
• Similarly, the href indirection (or similar) is not necessary as the @context already defines these as links ("@type": "@id")
• I'm not sure how to fit Eve's natural language descriptions of the relations in this, but again as by definition e.g. next expands into http://www.iana.org/assignments/link-relations/#next, these are arguably redundant
• Finally, / isn't specified as anything at the moment, so I'd suggest to not link it.

What do you think?

[spyysalo]

This works now:

$ curl 127.0.0.1:5000/annotations/

{
  "@context": "http://www.w3.org/ns/oa.jsonld",
  "@graph": [
    {
      "@id": "54f867f50cea86e16983750b",
      "target": "http://bionlp-corpora.sourceforge.net/CRAFT/1.0/16628246.txt#char=21911,21913"
      "body": "http://craft.ucdenver.edu/iao/sup",
    },
    ...
    {
      "@id": "54f867f50cea86e16983750d",
      "body": "http://craft.ucdenver.edu/iao/sup",
      "target": "http://bionlp-corpora.sourceforge.net/CRAFT/1.0/16628246.txt#char=21926,21931"
    }
  ],
  "@type": "http://www.w3.org/ns/hydra/core#Collection",
  "last": "annotations?page=1630",
  "next": "annotations?page=2"
}

Remaining TODO:

1. define relevant IANA link relations in @context
2. decide whether to keep http://www.w3.org/ns/hydra/core#Collection for type
3. documentation

[spyysalo]

1. define relevant IANA link relations in @context

Done: http://nlplab.org/ns/restoa-context-20150307.json