Updates to contract and API.html

openapi/contracts/core-provider.openapi.yaml

@@ -211,6 +211,9 @@ paths:
     post:
       summary: Query objects
       operationId: queryObjects
+      parameters:
+        - $ref: '#/components/parameters/PageLimit'
+        - $ref: '#/components/parameters/PageSkip'
       requestBody:
         required: true
         content:
@@ -225,12 +228,20 @@ paths:
           headers:
             Link:
               $ref: '#/components/headers/NextPageLink'
+            Pagination-Limit:
+              $ref: '#/components/headers/PaginationLimit'
+            Pagination-Skip:
+              $ref: '#/components/headers/PaginationSkip'
+            Pagination-Limit-Max:
+              $ref: '#/components/headers/PaginationLimitMax'
+            Pagination-Skip-Max:
+              $ref: '#/components/headers/PaginationSkipMax'
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/GenericArray'
         '400':
-          $ref: '#/components/responses/BadRequest'
+          $ref: '#/components/responses/PageBadRequest'
         '413':
           $ref: '#/components/responses/PayloadTooLarge'
         '415':
@@ -239,6 +250,9 @@ paths:
     post:
       summary: Search objects by keywords
       operationId: searchObjects
+      parameters:
+        - $ref: '#/components/parameters/PageLimit'
+        - $ref: '#/components/parameters/PageSkip'
       requestBody:
         required: true
         content:
@@ -256,12 +270,20 @@ paths:
           headers:
             Link:
               $ref: '#/components/headers/NextPageLink'
+            Pagination-Limit:
+              $ref: '#/components/headers/PaginationLimit'
+            Pagination-Skip:
+              $ref: '#/components/headers/PaginationSkip'
+            Pagination-Limit-Max:
+              $ref: '#/components/headers/PaginationLimitMax'
+            Pagination-Skip-Max:
+              $ref: '#/components/headers/PaginationSkipMax'
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/GenericArray'
         '400':
-          $ref: '#/components/responses/BadRequest'
+          $ref: '#/components/responses/PageBadRequest'
         '413':
           $ref: '#/components/responses/PayloadTooLarge'
         '415':
@@ -270,6 +292,9 @@ paths:
     post:
       summary: Search objects by phrase
       operationId: searchObjectsByPhrase
+      parameters:
+        - $ref: '#/components/parameters/PageLimit'
+        - $ref: '#/components/parameters/PageSkip'
       requestBody:
         required: true
         content:
@@ -287,12 +312,20 @@ paths:
           headers:
             Link:
               $ref: '#/components/headers/NextPageLink'
+            Pagination-Limit:
+              $ref: '#/components/headers/PaginationLimit'
+            Pagination-Skip:
+              $ref: '#/components/headers/PaginationSkip'
+            Pagination-Limit-Max:
+              $ref: '#/components/headers/PaginationLimitMax'
+            Pagination-Skip-Max:
+              $ref: '#/components/headers/PaginationSkipMax'
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/GenericArray'
         '400':
-          $ref: '#/components/responses/BadRequest'
+          $ref: '#/components/responses/PageBadRequest'
         '413':
           $ref: '#/components/responses/PayloadTooLarge'
         '415':
@@ -705,6 +738,33 @@ components:
         example: >-
           <http://store.rerum.io/v1/context.json>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json",
           <https://store.rerum.io/v1/api/query?limit=100&skip=200>; rel="next"
+    PaginationLimit:
+      description: >-
+        The 'limit' applied to this page, after any reduction to the maximum.  Read it rather than
+        assuming the requested 'limit' was served.
+      schema:
+        type: integer
+        minimum: 1
+    PaginationSkip:
+      description: >-
+        The 'skip' applied to this page.
+      schema:
+        type: integer
+        minimum: 0
+    PaginationLimitMax:
+      description: >-
+        The largest 'limit' served.  A larger 'limit' is reduced to it.
+      schema:
+        type: integer
+        minimum: 1
+        example: 500
+    PaginationSkipMax:
+      description: >-
+        The largest 'skip' accepted.  A larger 'skip' is a 400.
+      schema:
+        type: integer
+        minimum: 1
+        example: 100000
   parameters:
     ObjectId:
       in: path
@@ -726,6 +786,29 @@ components:
       description: Only expand with Annotations attributed to this creator.
       schema:
         type: string
+    PageLimit:
+      in: query
+      name: limit
+      required: false
+      description: >-
+        How many records to serve, as a whole number in plain decimal digits. A 'limit'
+        larger than 500 is reduced to 500 rather than rejected.
+      schema:
+        type: integer
+        minimum: 1
+        default: 100
+    PageSkip:
+      in: query
+      name: skip
+      required: false
+      description: >-
+        How many records to pass over before the page starts, as a whole number in plain decimal
+        digits.  A 'skip' beyond 100000 is rejected with a 400.
+      schema:
+        type: integer
+        minimum: 0
+        maximum: 100000
+        default: 0
   schemas:
     GenericObject:
       type: object
@@ -737,6 +820,15 @@ components:
   responses:
     BadRequest:
       description: Bad request — the request body was missing, empty, or otherwise invalid.
+    PageBadRequest:
+      description: >-
+        The request body was malformed.  It could also mean the 'limit' or 'skip' URL parameter 
+        was malformed or beyond the maximum.
+      headers:
+        Pagination-Limit-Max:
+          $ref: '#/components/headers/PaginationLimitMax'
+        Pagination-Skip-Max:
+          $ref: '#/components/headers/PaginationSkipMax'
     Unauthorized:
       description: Unauthorized — missing, malformed, or invalid bearer token.
     Forbidden:

public/API.html

@@ -490,7 +490,7 @@ <h3 id="custom-query">Custom Query</h3>
             </thead>
             <tbody>
                 <tr>
-                    <td><code class="language-plaintext highlighter-rouge">/query?limit=10&skip=0</code></td>
+                    <td><code class="language-plaintext highlighter-rouge">/query?limit=100&skip=0</code></td>
                     <td><code class="language-plaintext highlighter-rouge">{JSON}</code></td>
                     <td>200 <code class="language-plaintext highlighter-rouge">[{JSON}]</code></td>
                 </tr>
@@ -505,7 +505,7 @@ <h3 id="custom-query">Custom Query</h3>
         <p>
             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 100 records in the response to guard against unreasonable queries. To allow for more records in the response one can add the URL parameter <code>limit</code> 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 that follows the <code>rel="next"</code> link in each response's <code>Link</code> header until there is none. You will see an example of this below.
-            <p class="alert">A <code>limit</code> above the maximum of 500 is not an error. It is reduced to 500, and the response says so &mdash; see <a href="#pagination-parameters">Pagination parameters</a>. Read the applied value from the <code>Pagination-Limit</code> response header rather than assuming you received everything you asked for.</p>
+            <p class="alert">A <code>limit</code> above the maximum of 500 is not an error. It is reduced to 500, and the response says so &mdash; see <a href="#pagination-parameters">Pagination parameters</a>. Read the applied value from the <code>Pagination-Limit</code> response header rather than assuming you received everything you asked for. A <code>skip</code> above the maximum of 100000 is not reduced. It is a <code>400</code>.</p>
         </p>
         <p>
             <div class="exHeading">Non-Paged Query Javascript Example</div>
@@ -579,7 +579,7 @@ <h3 id="custom-query">Custom Query</h3>
         </p>
         <h3 id="pagination-parameters">Pagination parameters</h3>
         <p>
-            <code>limit</code> and <code>skip</code> are URL parameters shared by <a href="#custom-query">Custom Query</a>, <a href="#text-search">Text Search</a>, and <a href="#phrase-search">Phrase Search</a>. Both must be whole numbers written in plain decimal digits. Anything else is a <code>400</code>.
+            <code>limit</code> and <code>skip</code> are URL parameters shared by <a href="#custom-query">Custom Query</a>, <a href="#text-search">Text Search</a>, and <a href="#phrase-search">Phrase Search</a>. Both must be whole numbers written in plain decimal digits. Anything else is a <code>400</code>, and so is sending either one more than once.
         </p>
         <table>
             <thead>
@@ -676,7 +676,7 @@ <h3 id="text-search">Text Search</h3>
         </ul>
         <p>
             To allow for more records in the response one can add the URL parameter <code>limit</code> to the search requests. If you expect the search request will have a very large response with many objects, your application should use a paged search that follows the <code>rel="next"</code> link in each response's <code>Link</code> header until there is none. You will see an example of this below.
-            <p class="alert">A <code>limit</code> above the maximum of 500 is reduced to 500, and the response says so &mdash; see <a href="#pagination-parameters">Pagination parameters</a>. Read the applied value from the <code>Pagination-Limit</code> response header rather than assuming you received everything you asked for.</p>
+            <p class="alert">A <code>limit</code> above the maximum of 500 is reduced to 500, and the response says so &mdash; see <a href="#pagination-parameters">Pagination parameters</a>. Read the applied value from the <code>Pagination-Limit</code> response header rather than assuming you received everything you asked for. A <code>skip</code> above the maximum of 100000 is not reduced. It is a <code>400</code>.</p>
         </p>
         <p>
             Search behavior:
@@ -825,7 +825,7 @@ <h3 id="phrase-search">Phrase Search</h3>
         </ul>
         <p>
             To allow for more records in the response one can add the URL parameter <code>limit</code> to the search requests. If you expect the search request will have a very large response with many objects, your application should use a paged search that follows the <code>rel="next"</code> link in each response's <code>Link</code> header until there is none. You will see an example of this below.
-            <p class="alert">A <code>limit</code> above the maximum of 500 is reduced to 500, and the response says so &mdash; see <a href="#pagination-parameters">Pagination parameters</a>. Read the applied value from the <code>Pagination-Limit</code> response header rather than assuming you received everything you asked for.</p>
+            <p class="alert">A <code>limit</code> above the maximum of 500 is reduced to 500, and the response says so &mdash; see <a href="#pagination-parameters">Pagination parameters</a>. Read the applied value from the <code>Pagination-Limit</code> response header rather than assuming you received everything you asked for. A <code>skip</code> above the maximum of 100000 is not reduced. It is a <code>400</code>.</p>
         </p>
         <p>
             Search behavior: