Update documentation for pagination (#1435)

[Preview available](https://hayleycd.github.io/osv.dev/post-v1-query/) --------- Signed-off-by: Hayley Denbraver <denbraver@google.com> Co-authored-by: olivekl <83081275+olivekl@users.noreply.github.com>
google · Jul 14, 2023 · 84ae1d2 · 84ae1d2
1 parent faf30a1
commit 84ae1d2
Show file tree

Hide file tree

Showing 2 changed files with 91 additions and 7 deletions.
diff --git a/docs/api/post-v1-query.md b/docs/api/post-v1-query.md
@@ -25,11 +25,12 @@ To query multiple packages at once, see further information [here](post-v1-query
 ## Parameters
 
 |---
-| Parameter | Type   | Description                                                                                                                 |
-| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
-| `commit`  | string | The commit hash to query for. If specified, `version` should not be set.                                                    |
-| `version` | string | The version string to query for. A fuzzy match is done against upstream versions. If specified, `commit` should not be set. |
-| `package` | object | The package to query against. When a `commit` hash is given, this is optional.                                              |
+| Parameter         | Type   | Description                                                                                                                                                    |
+| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `commit`          | string | The commit hash to query for. If specified, `version` should not be set.                                                                                       |
+| `version`         | string | The version string to query for. A fuzzy match is done against upstream versions. If specified, `commit` should not be set.                                    |
+| `package`         | object | The package to query against. When a `commit` hash is given, this is optional.                                                                                 |
+| `page_token`      | string | If your previous query fetched a large number of results, the response will be paginated. This is an optional field. Please see the (#pagination)  |
 
 Package Objects can be described by package name AND ecosystem OR by the package URL. 
 
@@ -49,7 +50,8 @@ Package Objects can be described by package name AND ecosystem OR by the package
     "name": "string",
     "ecosystem": "string",
     "purl": "string"
-  }
+  },
+  "next_page_token": "string",
 }
 ```
 
@@ -120,4 +122,27 @@ curl -d \
   ]
 }
 
-```
+```
+
+## Pagination
+For queries that result in a large number of vulnerabilities, the response will be paginated. In this case, the "next_page_token" is given in the response, indicating that there are more results to return. You will need to run additional queries using the `page_token` to see the remaining results, repeating queries until the `next_page_token` is no longer included in the response. 
+
+A response indicating pagination will be in this form:
+```json
+{
+  "vulns": [
+    ...
+  ],
+  "next_page_token": "a base64 string here"
+}
+```
+
+To get the next page of results, your next request must include page_token:
+```bash
+
+curl -d \
+  '{"package": {...}, "version": ..., "page_token": next_page_token from response}' \
+  "https://api.osv.dev/v1/query"
+
+```
+
diff --git a/docs/api/post-v1-querybatch.md b/docs/api/post-v1-querybatch.md
@@ -23,6 +23,8 @@ Query for multiple packages (by either package and version or git commit hash) a
 
 The parameters are the same as those in found [here](post-v1-query.md#parameters), but you can make multiple queries.
 
+[Instructions are available](#pagination) for handling pagination for querybatch requests. 
+
 ## Payload
 ```json
 {
@@ -157,4 +159,61 @@ EOF
         }
     ]
 }
+```
+
+## Pagination
+
+Pagination for the querybatch API works similarly to the individual query. However, a querybatch request may return results with a `next_page_token` for only a few of the total queries. In this situation, you will need to run additional requests  for those specific queries to see the remaining results.
+
+A queryset response with paginated results will be in this form:
+
+```json
+{
+  "results": [
+    {
+      "vulns": [
+        ...
+      ],
+      "next_page_token": "token for query 1"
+    },
+    {
+      "vulns": [
+        ...
+      ],
+      "next_page_token": "token for query 2"
+    },
+    {
+      "vulns": [
+        ...
+      ],
+    },
+    ...
+  ]
+}
+```
+Notice that each result has a distinct "next_page_token" and that the third result does not include a `next_page_token`. This indicates that all of the vulnerabilities for the third query have been returned. 
+
+To get the next page of results, your next request should specify `page_token` only for the queries that returned `next_page_token`. 
+
+```bash
+cat <<EOF | curl -d @- "https://api.osv.dev/v1/querybatch"
+{
+  "queries": [
+    {
+      "package": {
+        ...
+      },
+      "version": ..., 
+      "page_token": next_page_token from query 1,
+    },
+    {
+      "package": {
+        ...
+      },
+      "version": ...,
+      "page_token": next_page_token from query 2,
+    },
+  ]
+}
+EOF
 ```