#9 Refactoring pagination documentation to use limit/offfset paramete…

…rs and the HTTP Link header.
1EdTech · Feb 28, 2019 · d5f3d26 · d5f3d26
1 parent c44e813
commit d5f3d26
Showing 1 changed file with 28 additions and 33 deletions.
diff --git a/ob-connect_v1p0_draft.html b/ob-connect_v1p0_draft.html
@@ -405,14 +405,6 @@ <h3>Envelope</h3>
         <p>Responses from all APIs in this document are wrapped in an API envelope.</p>
           <pre>
 {
-    "pagination": {
-        "page": 2,
-        "perPage": 10,
-        "prevPage": "https://host.example.com/v1/assertions?page=2&perPage=10&since=2018-01-01",
-        "nextPage": null,
-        "totalResultCount": 11
-    },
-
     "status": {
         "error": null,
         "statusCode": 200,
@@ -430,7 +422,14 @@ <h3>Envelope</h3>
           </pre>
         <section id="api-envelope-pagination">
           <h4>Pagination</h4>
-          <p>The "pagination" property MUST appear when a list response is incomplete and MUST include all of the following keys except "totalResultCount". The "pagination" property MAY appear for complete responses.</p>
+          <p>Pagination is controlled by two query string parameters appended to the request.</p>
+          <ul>
+            <li><code>limit</code> - the number of results to return</li>
+            <li><code>offset</code> - the index of the first record to return (zero indexed)</li>
+          </ul>
+          <p>The HTTP <code>Link</code> header MUST appear when a list response is incomplete and MAY appear for complete responses.</p>
+          <p>It is RECOMMENDED that Host implementations pass the total result count back to the requester. When the total result count is not known, this MUST be omitted. The value MUST be provided in the custom HTTP header: <code>X-Total-Count</code>.</p>
+          <p>The header MUST support all of the following link relations (<code>rel</code> values):</p>
           <table>
             <thead>
               <tr>
@@ -440,27 +439,31 @@ <h4>Pagination</h4>
             </thead>
             <tbody>
               <tr>
-                <td>page</td>
-                <td>An integer representing the current page of results.</td>
-              </tr>
-              <tr>
-                <td>perPage</td>
-                <td>An integer representing the number of results accepted to be displayed on the current page. A client MAY request any number of results, and the platform MAY limit the acceptable perPage values to any number of 10 or more.</td>
+                <td>next</td>
+                <td>The link relation for the immediate next page of results. This MUST appear when the current list response is incomplete.</td>
               </tr>
               <tr>
-                <td>nextPage</td>
-                <td>A nullable string that contains the fully qualified URL of the next page after the current page.</td>
+                <td>last</td>
+                <td>The link relation for the last page of results. This MUST always appear.</td>
               </tr>
               <tr>
-                <td>prevPage</td>
-                <td>A nullable string that contains the fully qualified URL of the previous page before the current page.</td>
+                <td>first</td>
+                <td>The link relation for the first page of results. This MUST always appear.</td>
               </tr>
               <tr>
-                <td>totalResultCount</td>
-                <td>The Host should include the total number of results responsive to the request. If the total number is not known, "totalResultCount" MUST be omitted.</td>
+                <td>prev</td>
+                <td>The link relation for the immediate previous page of results. This MUST appear when the offset is greater than zero.</td>
               </tr>
             </tbody>
           </table>
+          <p>An example of Link header pagination, line breaks added for readability:</p>
+          <pre>
+Link:
+&lt;https://host.example.com/v1/assertions?limit=10&offset=20&gt;; rel="next",
+&lt;https://host.example.com/v1/assertions?limit=3&offset=500&gt;; rel="last",
+&lt;https://host.example.com/v1/assertions?limit=10&offset=0&gt;; rel="first",
+&lt;https://host.example.com/v1/assertions?limit=10&offset=0&gt;; rel="prev"
+          </pre>
         </section>
         <section id="api-envelope-status">
           <h4>Status</h4>
@@ -521,14 +524,14 @@ <h4>Assertions</h4>
                         </thead>
                         <tbody>
                           <tr>
-                            <td>page</td>
+                            <td>limit</td>
                             <td>Integer</td>
-                            <td>Indicate which page of the results should be retrieved.</td>
+                            <td>Indicate how many results should be retrieved in a single page.</td>
                           </tr>
                           <tr>
-                            <td>perPage</td>
+                            <td>offset</td>
                             <td>Integer</td>
-                            <td>Indicate how many results should be retrieved in a single page.</td>
+                            <td>Indicate the index of the first record to return (zero indexed).</td>
                           </tr>
                           <tr>
                             <td>since</td>
@@ -780,14 +783,6 @@ <h3>Responses</h3>
           <h4>200 GET Assertions Response</h4>
           <pre>
 {
-    "pagination": {
-        "page": 2,
-        "perPage": 10,
-        "prevPage": "https://host.example.com/v1/assertions?page=2&perPage=10&since=2018-01-01",
-        "nextPage": null,
-        "totalResultCount": 11
-    },
-
     "status": {
         "error": null,
         "statusCode": 200,