Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define client-initiated pagination #184

Merged
merged 5 commits into from
Mar 19, 2019
Merged

Define client-initiated pagination #184

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3d49d3a
Added two predicates allowing to address offset/limit pair for IRI te…
alien-mcl Feb 11, 2019
fbca986
Added separate predicate for page identifier
alien-mcl Feb 14, 2019
c676464
Added specification paragraphs related to paginations. Predicate chan…
alien-mcl Feb 20, 2019
c27deef
Added range and subPropertyOf for hydra:pageIndex
alien-mcl Feb 25, 2019
a6c54dc
Merge branch 'master' of https://github.com/HydraCG/Specifications in…
alien-mcl Feb 25, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions spec/latest/core/core.jsonld
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,10 @@
"mapping": "hydra:mapping",
"IriTemplateMapping": "hydra:IriTemplateMapping",
"variable": "hydra:variable",
"offset": { "@id": "hydra:offset", "@type": "xsd:nonNegativeInteger" },
"limit": { "@id": "hydra:limit", "@type": "xsd:nonNegativeInteger" },
"pageIndex": { "@id": "hydra:pageIndex", "@type": "xsd:nonNegativeInteger" },
"pageReference": { "@id": "hydra:pageReference" },
"defines": { "@reverse": "rdfs:isDefinedBy" },
"comment": "rdfs:comment",
"label": "rdfs:label",
Expand Down Expand Up @@ -532,6 +536,38 @@
"domain": "hydra:IriTemplateMapping",
"range": "xsd:string",
"vs:term_status": "testing"
},
{
"@id": "hydra:offset",
"@type": "rdf:Property",
"label": "skip",
"comment": "Instructs to skip N elements of the set.",
"range": "xsd:nonNegativeInteger",
"vs:term_status": "testing"
},
{
"@id": "hydra:limit",
"@type": "rdf:Property",
"label": "take",
"comment": "Instructs to limit set only to N elements.",
"range": "xsd:nonNegativeInteger",
"vs:term_status": "testing"
},
{
"@id": "hydra:pageIndex",
"@type": "rdf:Property",
"subPropertyOf": "hydra:pageReference",
"label": "page index",
"comment": "Instructs to provide a specific page of the collection at a given index.",
"range": "xsd:nonNegativeInteger",
"vs:term_status": "testing"
},
{
"@id": "hydra:pageReference",
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it only me or pageReference still does not make much sense? Can't we just go with offset, limit and pageIndex for now and create another issue or PR before we add it to the vocab.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We wouldn't like to limit possible usages only to numeric pages - that's why pageIndex. I've recently added a subPropertyOf relation between pageIndex and pageReference - it feels natural this way.
Both predicates has similar semantics - here client you can point to a specific page of the set. The extra thing that comes with pageIndex is it's cleanness, which covers most use cases.
While it is not possible to provide i.e. min/max range or other means of expressing allowed values for pageReference, this predicate still can be used as it is now with some success.

"@type": "rdf:Property",
"label": "page reference",
"comment": "Instructs to provide a specific page reference of the collection.",
"vs:term_status": "testing"
}
]
}
20 changes: 20 additions & 0 deletions spec/latest/core/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -989,6 +989,26 @@ <h3>Description of HTTP Status Codes and Errors</h3>
-->
</pre>
</section>

<section>
<h3>Client initiated pagination</h3>

<p>There are situations when a client would like to provide a specific
collection limitations, i.e. by providing query-language like member
offset and limit or some specific page index and number of members
per page. This is doable with <i>offset</i>/<i>limit</i> or
<i>pageIndex</i>/<i>limit</i> predicates.</p>

<p>With those, it is possible to bind a template variables mapped
with externally obtained values (i.e. user interaction) the same way
as with other mappings.</p>

<p>While the predicates enlisted above accepts non-negative integer
numbers, there is also a possibility of providing a custom page
reference expressed via <i>pageReference</i> predicate. It is possible
to provide a custom page identifier (i.e. a GUID or a letter)
instead of a number.</p>
</section>
</section>

<!-- <section>
Expand Down