This simple format will be made more complex in the future, but should serve the basic needs as it is.
- RERUM will test for property matches. By default, this is limited to 10 records in the response to guard against unreasonable queries. To allow for more records in the response one can add the URL parameter limit to the query requests. If you expect the query request will have a very large response with many objects, your application should use a paged query by also using the skip URL parameter. You will see an example of this below.
-
Note that your application may experience strange behavior with large limits, such as ?limit=1000. It is recommended to use a limit of 100 or less. If you expect there are more than 100 matching records, use a paged query to make consecutive requests until all records all gathered.
+ RERUM will test for property matches. By default, this is limited to 100 records in the response to guard against unreasonable queries. To allow for more records in the response one can add the URL parameterlimit to the query requests. If you expect the query request will have a very large response with many objects, your application should use a paged query by also using the skip URL parameter. You will see an example of this below.
+ A limit above the maximum of 500 is not an error. It is reduced to 500, and the response says so — see Pagination parameters. Read the applied value from the Pagination-Limit response header rather than assuming you received everything you asked for.
const many_results = await pagedQuery(100, 0, {"type": "Thing"})
- function pagedQuery(lim, it = 0, queryObj, allResults = []) {
- return fetch(`https://devstore.rerum.io/v1/api/query?limit=${lim}&skip=${it}`, {
+ async function pagedQuery(lim, it = 0, queryObj, allResults = []) {
+ const response = await fetch(`https://devstore.rerum.io/v1/api/query?limit=${lim}&skip=${it}`, {
method: "POST",
headers: {
"Content-Type": "application/json; charset=utf-8"
},
body: JSON.stringify(queryObj)
})
- .then(response => response.json())
- .then(results => {
- if (results.length) {
- allResults = allResults.concat(results)
- return pagedQuery(lim, it + results.length, queryObj, allResults)
- }
+ // Only the skip ceiling ends a walk early. Every other 400 is a real error, and
+ // returning the pages gathered so far would report a walk that never finished.
+ // Stopping at the ceiling still truncates, so say so rather than returning quietly.
+ const skipMax = Number(response.headers.get("Pagination-Skip-Max"))
+ if (response.status === 400 && skipMax && it > skipMax) {
+ console.warn(`Stopped at the skip ceiling of ${skipMax}. These results are incomplete. Narrow the query.`)
return allResults
- })
- .catch(err => {
- console.warn("Could not process a result in paged query")
- throw err
- })
+ }
+ if (!response.ok) throw new Error(await response.text())
+ const results = await response.json()
+ // Append in place. Walking to the skip ceiling at this page size is a thousand pages,
+ // and concat() would copy every record gathered so far on each one of them.
+ allResults.push(...results)
+
+ // Advance by the page size the server applied, which may be smaller than the one you asked for.
+ const appliedLimit = Number(response.headers.get("Pagination-Limit")) || lim
+
+ // A short page is the last page. Do not wait for an empty one.
+ if (results.length < appliedLimit) return allResults
+ return pagedQuery(lim, it + appliedLimit, queryObj, allResults)
}
+ limit and skip are URL parameters shared by Custom Query, Text Search, and Phrase Search. Both must be whole numbers written in plain decimal digits. Anything else is a 400.
+
| Parameter | +Default | +Maximum | +Rules | +
|---|---|---|---|
limit |
+ 100 | +500 | +A whole number of 1 or greater. Above the maximum it is reduced to the maximum, and Pagination-Limit reports what was applied. |
+
skip |
+ 0 | +100000 | +A whole number of 0 or greater. Above the maximum it is a 400 naming the maximum, because clamping it would return the page at the maximum over and over. |
+
+ Every paged response reports what was applied and what the maximums are, so a client can configure itself from any single response and tell a truncated page from a genuine final one. These headers are readable cross-origin. +
+
+ Pagination-Limit-Max and Pagination-Skip-Max are reported on rejections too, including the 400 for a skip past the maximum. That is what lets a paged walk recognise the depth boundary and stop cleanly.
+
+
+ Pagination-Limit: 500
+ Pagination-Skip: 0
+ Pagination-Limit-Max: 500
+ Pagination-Skip-Max: 100000
+
+ Custom Query pages in ascending _id order, on both POST and HEAD. A skip offset only means something over a fixed order, so consecutive pages tile that order without repeating or missing a record.
+
This is not oldest-to-newest. RERUM _id values are a mix of BSON types across the repository's history, and BSON sorts each type into its own block, so the order is stable and complete but carries no chronological meaning. Sort client-side on __rerum.createdAt if you need records in the order they were made.
+ The search endpoints page in descending relevance score, which you can read back from __rerum.score on each result. That order is the same across both the IIIF 3.0 and IIIF 2.1 indexes, so the best match is the first record of the first page whichever shape it was written in.
+
Descending score is an ordering, not a tiling guarantee. Custom Query is the endpoint to walk when you need every matching record exactly once.
+