From c87b13a8bdb81e3178370ad15e797a4d289a4106 Mon Sep 17 00:00:00 2001
From: Jeremy Adams <jeremy.adams@ga4gh.org>
Date: Tue, 14 Sep 2021 10:24:29 -0400
Subject: [PATCH] added "Link" header and "page" query parameter for paginated
 traversal of contents

---
 .../components/parameters/ContentsPage.yaml   |  7 +++
 .../components/responses/200OkDrsObject.yaml  | 50 +++++++++++++++++++
 openapi/paths/objects@{object_id}.yaml        |  1 +
 3 files changed, 58 insertions(+)
 create mode 100644 openapi/components/parameters/ContentsPage.yaml

diff --git a/openapi/components/parameters/ContentsPage.yaml b/openapi/components/parameters/ContentsPage.yaml
new file mode 100644
index 00000000..847fed14
--- /dev/null
+++ b/openapi/components/parameters/ContentsPage.yaml
@@ -0,0 +1,7 @@
+in: query
+name: page
+schema:
+  type: integer
+example: 5
+description: >-
+  For paginated traversal of the `contents` array of a DRS Object bundle. Indicates the requested "page" or subset of `contents` objects. 
diff --git a/openapi/components/responses/200OkDrsObject.yaml b/openapi/components/responses/200OkDrsObject.yaml
index e8f990ed..294e7980 100644
--- a/openapi/components/responses/200OkDrsObject.yaml
+++ b/openapi/components/responses/200OkDrsObject.yaml
@@ -1,4 +1,54 @@
 description: The `DrsObject` was found successfully
+headers:
+  Link:
+    description: |
+      Pagination links to retrieve the `contents` array of a DRS Object bundle via paginated traversal.
+
+      #### Link header structure
+
+      The value of the `Link` header is a **comma-delimited** list of entries. Each entry in the list contains:
+      1. A URL that clients can request to obtain a new subset of `contents` for the same DRS Object
+      2. A `rel` (relation) keyword, indicating the direction of traversal (e.g. next page, previous page, etc.)
+
+      The correct format for a pagination link is as follows: 
+
+      `<{url}>; rel="${rel_keyword}"`
+
+      i.e.:
+      * The URL must be encapsulated in angle brackets
+      * The `rel` keyword must be preceded by an explicit `rel=` indicator and encapsulated in double quotes
+      * The URL and `rel` keyword must be separated by `; `
+
+      #### `rel` keywords
+
+      Standardized `rel` keywords inform the client of the traversal direction of each URL in the `Link` header, enabling dynamic traversal. The following table outlines the acceptable `rel` keywords and what they mean:
+
+      | `rel` value | description |
+      |-------------|-------------|
+      | next | URL retrieves the next page of `contents` objects compared to the current page the client is on |
+      | prev | URL retrieves the previous page of `contents` objects compared to the current page the client is on |
+      | first | URL jumps to the first page of `contents` objects |
+      | last | URL jumps to the final page of `contents` objects |
+
+      Only `rel="next"` links are mandatory for unidirectional traversal. The other `rel` links are optional, and can be left up to individual implementers if they wish to enable multidirectional traversal for their DRS service.
+
+      #### Example Link header
+
+      The following snippet displays an example `Link` header value for paginated traversal. In the example, the client most recently obtained page `14` of `contents` objects for the DRS Object with an ID of `314159`, out of a total `34` pages.
+
+      ```
+      Link: <https://drs.example.org/ga4gh/drs/v1/objects/314159?page=15>; rel="next",
+      <https://drs.example.org/ga4gh/drs/v1/objects/314159?page=34>; rel="last",
+      <https://drs.example.org/ga4gh/drs/v1/objects/314159?page=1>; rel="first",
+      <https://drs.example.org/ga4gh/drs/v1/objects/314159?page=13>; rel="prev"
+      ```
+
+      **Note:** Pagination in DRS is modeled after [Github's approach and documentation](https://docs.github.com/en/rest/guides/traversing-with-pagination).
+
+
+
+    schema:
+      type: string
 content:
   application/json:
     schema:
diff --git a/openapi/paths/objects@{object_id}.yaml b/openapi/paths/objects@{object_id}.yaml
index d4aea640..22217f8f 100644
--- a/openapi/paths/objects@{object_id}.yaml
+++ b/openapi/paths/objects@{object_id}.yaml
@@ -6,6 +6,7 @@ get:
   parameters:
     - $ref: '../components/parameters/ObjectId.yaml'
     - $ref: '../components/parameters/Expand.yaml'
+    - $ref: '../components/parameters/ContentsPage.yaml'
   responses:
     200:
       $ref: '../components/responses/200OkDrsObject.yaml'