Re: Pagination (ISSUE-42)

Hi,

I want to re-phrase my proposal because my previous attempt appears to
cause misunderstandings.

This is not only a reply to Andrew, I'd like to ask everybody to
consider my proposal.

Am 15.02.2015 um 13:37 schrieb Andrew Hacking:
> 
> 
> On Sat, Feb 14, 2015 at 5:55 PM, Dietrich Schulten <ds@escalon.de
> <mailto:ds@escalon.de>> wrote:
> 
>     Hi Andrew,
> 
>     Am 13.02.2015 um 02:51 schrieb Andrew Hacking:
>     >
>     > What I mean by the above is that collections should not have any related
>     > resource content in them as their primary content.
> 
>     See proposal below - would that cut it?
> 
> 
> Probably not, see below.

@Andrew:
I am afraid you mistook the illustration of the current collection
design for my proposal. I certainly mislead you by first giving a long
example of the current design and only later making the proposal.

My proposal is:

1. Use hydra:Collection not as a container but as a descriptor, i.e.
keep the actual items outside of the hydra:Collection object and make
them direct values of the property they belong to. Drop hydra:member.
@Andrew: the @context is restricted to define terms in the context, it
is not a place to make arbitrary statements about things.

2. Use a hydra:IriTemplate on hydra:Collection at the *origin* object to
inform the client about possible paging or ranged access. To support
ranged access, introduce hydra:partial, hydra:offset and hydra:limit
(see below for usage). Also use the Collection descriptor to inform the
client about methods that can be performed on the collection, such as
POSTing to it or searching inside it.

3. Let the list of items be a plain list without surrounding container
because such a container around the items causes problems in the RDF
model. ("/alice foaf:knows hydra:Collection" makes RDF tools think that
the hydra:Collection is a foaf:Person because foaf:knows defines that
its values are foaf:Person)

4. The list of items can either be added as direct property values to
the origin object (coming from HAL I call this embedding) or it can be
kept outside, in which case the property value is a link. If that link
is dereferenced, you get a plain list of items without surrounding
container. See example responses below.

5. In order to say things about the collection directly in the context
of the collection response, we must use something else but the
collection response body, because the body contains just items and there
is nothing to attach additional properties to the collection. Proposal:
use rfc-5988 Link headers for that. We can use the registered IANA rels
'next', 'prev' for paging. We can also use any Linked Data attribute to
point to anything from the collection response because non-registered
rels (aka extension rels) are URIs. We already use Link-Header for other
purposes, so this is not an entirely new thing.

6. We could use the Link-Template header [1] to inform the client about
the offset/limit template inside the collection response. But
Link-Template is a draft. (The Link header is not suitable for
templates, because its href must be a URI, not a URITemplate.)

For examples, see below.

[1] http://tools.ietf.org/html/draft-nottingham-link-template-01

Example responses illustrating my proposal:

> 
>     // server embeds a collection of people Alice knows
>     {
>       "@id": "/alice",
>       "foaf:name": "Alice",
>       "foaf:knows": [
>         {"@id":"/bob", "foaf:name": "Robert Rumbaugh"},
>         {"@id":"/zelda", "foaf:name": "Zelda Zackney"}
>       ],
>       "collection": [
>         {
>         "@id": "/alice/friends",
>         "@type": "Collection",
>         "manages": {
>           "property": "foaf:knows",
>           "subject": "/alice"
>         },
>         "search" : ... an iritemplate,
>         "operation" : ... supportedOperations on /alice/friends
>       ]
>     }
> 
> 
>     // server points to external resource with offset/limit
>     {
>       "@id" : "/alice"
>       // plain link to friends:
>       "foaf:knows" : { "@id": "/alice/friends" },
>       // saying things about the management of /alice/friends:
>       "collection": [
>         {
>         "@id": "/alice/friends",
>         "@type": "Collection",
>         "manages": {
>           "property": "foaf:knows",
>           "subject": "/alice"
>         },
>         "partial": {
>             "@type": "IriTemplate",
>             "template": /alice/friends{?offset,limit}
>             "mapping": [
>               {
>               "@type": "IriTemplateMapping",
>               "variable": "offset",
>               "property": "hydra:offset"
>               },
>               {
>               "@type": "IriTemplateMapping",
>               "variable": "limit",
>               "property": "hydra:limit",
>               }
>             ]
>         }
>       }
>     }
> 

>     The target resource returned from /alice/friends is a json-ld set of
>     foaf:Person, not a hydra:Collection.
> 
   The response has the following link header to point to the
   next page.

   Header:
   Link: <http://example.com/alice/friends?page=2>; rel="next"
   Body:
>     [
>       {"@id":"/bob",
>        "@type": "http://xmlns.com/foaf/0.1/Person",
>        "http://xmlns.com/foaf/0.1/name": "Robert Rumbaugh"
>       },
>       {"@id":"/zelda",
>        "@type": "http://xmlns.com/foaf/0.1/Person",
>        "http://xmlns.com/foaf/0.1/name": "Zelda Zackney"
>       }
>     ]
> 

Best regards,
Dietrich

Received on Monday, 16 February 2015 09:48:05 UTC