document cursor paging for disposition updates

bundled/minfraud.yaml

@@ -197,19 +197,28 @@ paths:
     get:
       operationId: listDispositionUpdates
       summary: List disposition and note updates
-      description: Returns transactions whose disposition or note changed, through the account portal's manual review, after `updates_after`. Use this only if you set dispositions or notes from the account portal and need those changes in your own system.
+      description: |-
+        Returns transactions whose disposition or note changed, through the account portal's manual review, after `updates_after` or `cursor`. Use this only if you set dispositions or notes from the account portal and need those changes in your own system.
+
+        Send `updates_after` on the first request. To get the next page, send the response's `next_cursor` as `cursor`. MaxMind returns a change one minute or more after it happens.
       tags:
         - Dispositions
       externalDocs:
         url: https://dev.maxmind.com/minfraud/working-with-transaction-dispositions/
       parameters:
         - name: updates_after
           in: query
-          required: true
-          description: An exclusive lower bound, as an RFC 3339 timestamp. MaxMind returns only updates made after this time. URL-encode the value, for example send a `+` in the UTC offset as `%2B`. Pass the previous response's `last_update_timestamp` to page through results.
+          required: false
+          description: An exclusive lower bound, as an RFC 3339 timestamp. MaxMind returns only updates made after this time. URL-encode the value, for example send a `+` in the UTC offset as `%2B`. Send `updates_after` or `cursor`, not both.
           schema:
             type: string
             format: date-time
+        - name: cursor
+          in: query
+          required: false
+          description: The `next_cursor` value from the previous response. MaxMind returns the updates after the position that `next_cursor` marks. Send `updates_after` or `cursor`, not both.
+          schema:
+            type: string
       responses:
         '200':
           description: The transactions with a disposition or note update.
@@ -433,8 +442,10 @@ components:
     DispositionBadRequest:
       description: |-
         The request is not valid. The `code` is one of:
-        - `UPDATES_AFTER_REQUIRED`: the request has no `updates_after` parameter, or its value is empty.
+        - `UPDATES_AFTER_REQUIRED`: `updates_after` and `cursor` are both missing or empty.
         - `TIMESTAMP_INVALID`: `updates_after` is not a valid RFC 3339 timestamp.
+        - `CURSOR_INVALID`: `cursor` is not valid. Send a `next_cursor` value from a previous response.
+        - `CURSOR_AND_UPDATES_AFTER_PROVIDED`: `updates_after` and `cursor` both have a value.
       content:
         application/vnd.maxmind.com-error+json:
           schema:
@@ -1873,15 +1884,19 @@ components:
       type: object
       required:
         - last_update_timestamp
+        - next_cursor
         - updates
       properties:
         last_update_timestamp:
           type: string
           format: date-time
-          description: The sort timestamp of the last transaction in `updates`, in RFC 3339 format. This can differ from that transaction's `action_last_updated` and `note_last_updated`. Pass this value as `updates_after` in your next request. An empty `updates` array means there are no updates after `updates_after` yet. This value is then not a transaction's timestamp, so keep your current `updates_after` for the next request.
+          description: The sort timestamp of the last transaction in `updates`, in RFC 3339 format. This can differ from that transaction's `action_last_updated` and `note_last_updated`. If `updates` is empty, this is the time of the request's `updates_after`, or the `last_update_timestamp` of the response that gave the `cursor`. To page, send `next_cursor` as `cursor`. Do not send this value as `updates_after` after a `cursor` request. Several updates can have the same timestamp, and a `cursor` response can hold only some of them. For example, if three updates share this timestamp and the response holds one, a request with this value as `updates_after` never returns the other two.
+        next_cursor:
+          type: string
+          description: An opaque value for the position of the last transaction in `updates`. Send it as `cursor` in your next request to get the updates after that transaction. Do not parse or build this value. If `updates` is empty, this is the request's position. Send it again later to get new updates.
         updates:
           type: array
-          description: The transactions with a disposition or note update after `updates_after`, including a transaction whose manual review period expired. MaxMind sorts in ascending order by the earliest update timestamp, either the disposition or the note, after `updates_after`. A response usually holds at most 1000 updated transactions. Do not rely on this limit. A transaction can appear in more than one response, for example when its note changes after its disposition, so process updates idempotently.
+          description: The transactions with a disposition or note update after `updates_after` or `cursor`, including a transaction whose manual review period expired. MaxMind sorts in ascending order by the earliest update timestamp, either the disposition or the note, after that position. A response to `cursor` holds at most 1000 updated transactions. MaxMind can change this number. A response to `updates_after` can hold more, because it holds every update that shares its last timestamp. A transaction can appear in more than one response, for example when its note changes after its disposition, so process updates idempotently.
           items:
             $ref: '#/components/schemas/DispositionUpdate'
   examples:
@@ -2435,6 +2450,7 @@ components:
       summary: Disposition updates response
       value:
         last_update_timestamp: '2017-03-15T22:06:22.492945Z'
+        next_cursor: 00054acc27a57911deadbeef000000000000000000000050
         updates:
           - minfraud_id: deadbeef-0000-0000-0000-000000000003
             action: manual_review
@@ -2470,4 +2486,4 @@ components:
       summary: Dispositions UPDATES_AFTER_REQUIRED response
       value:
         code: UPDATES_AFTER_REQUIRED
-        error: You have not supplied the updates_after URI parameter.
+        error: The updates_after or cursor URL parameter is required.

components/minfraud-response.yaml

@@ -645,6 +645,7 @@ schemas:
     type: object
     required:
       - last_update_timestamp
+      - next_cursor
       - updates
     properties:
       last_update_timestamp:
@@ -653,19 +654,33 @@ schemas:
         description: >-
           The sort timestamp of the last transaction in `updates`, in RFC 3339
           format. This can differ from that transaction's `action_last_updated`
-          and `note_last_updated`. Pass this value as `updates_after` in your
-          next request. An empty `updates` array means there are no updates
-          after `updates_after` yet. This value is then not a transaction's
-          timestamp, so keep your current `updates_after` for the next request.
+          and `note_last_updated`. If `updates` is empty, this is the time of
+          the request's `updates_after`, or the `last_update_timestamp` of the
+          response that gave the `cursor`. To page, send `next_cursor` as
+          `cursor`. Do not send this value as `updates_after` after a `cursor`
+          request. Several updates can have the same timestamp, and a `cursor`
+          response can hold only some of them. For example, if three updates
+          share this timestamp and the response holds one, a request with this
+          value as `updates_after` never returns the other two.
+      next_cursor:
+        type: string
+        description: >-
+          An opaque value for the position of the last transaction in `updates`.
+          Send it as `cursor` in your next request to get the updates after that
+          transaction. Do not parse or build this value. If `updates` is empty,
+          this is the request's position. Send it again later to get new
+          updates.
       updates:
         type: array
         description: >-
           The transactions with a disposition or note update after
-          `updates_after`, including a transaction whose manual review period
-          expired. MaxMind sorts in ascending order by the earliest update
-          timestamp, either the disposition or the note, after `updates_after`.
-          A response usually holds at most 1000 updated transactions. Do not
-          rely on this limit. A transaction can appear in more than one
+          `updates_after` or `cursor`, including a transaction whose manual
+          review period expired. MaxMind sorts in ascending order by the
+          earliest update timestamp, either the disposition or the note, after
+          that position. A response to `cursor` holds at most 1000 updated
+          transactions. MaxMind can change this number. A response to
+          `updates_after` can hold more, because it holds every update that
+          shares its last timestamp. A transaction can appear in more than one
           response, for example when its note changes after its disposition, so
           process updates idempotently.
         items:

examples/minfraud/disposition-bad-request.yaml

@@ -1,4 +1,4 @@
 summary: Dispositions UPDATES_AFTER_REQUIRED response
 value:
   code: UPDATES_AFTER_REQUIRED
-  error: You have not supplied the updates_after URI parameter.
+  error: The updates_after or cursor URL parameter is required.

examples/minfraud/disposition-updates.yaml

@@ -1,6 +1,7 @@
 summary: Disposition updates response
 value:
   last_update_timestamp: "2017-03-15T22:06:22.492945Z"
+  next_cursor: "00054acc27a57911deadbeef000000000000000000000050"
   updates:
     - minfraud_id: deadbeef-0000-0000-0000-000000000003
       action: manual_review

specs/minfraud.yaml

@@ -220,25 +220,39 @@ paths:
       summary: List disposition and note updates
       description: >-
         Returns transactions whose disposition or note changed, through the
-        account portal's manual review, after `updates_after`. Use this only if
-        you set dispositions or notes from the account portal and need those
-        changes in your own system.
+        account portal's manual review, after `updates_after` or `cursor`. Use
+        this only if you set dispositions or notes from the account portal and
+        need those changes in your own system.
+
+
+        Send `updates_after` on the first request. To get the next page, send
+        the response's `next_cursor` as `cursor`. MaxMind returns a change one
+        minute or more after it happens.
       tags:
         - Dispositions
       externalDocs:
         url: https://dev.maxmind.com/minfraud/working-with-transaction-dispositions/
       parameters:
         - name: updates_after
           in: query
-          required: true
+          required: false
           description: >-
             An exclusive lower bound, as an RFC 3339 timestamp. MaxMind returns
             only updates made after this time. URL-encode the value, for example
-            send a `+` in the UTC offset as `%2B`. Pass the previous response's
-            `last_update_timestamp` to page through results.
+            send a `+` in the UTC offset as `%2B`. Send `updates_after` or
+            `cursor`, not both.
           schema:
             type: string
             format: date-time
+        - name: cursor
+          in: query
+          required: false
+          description: >-
+            The `next_cursor` value from the previous response. MaxMind returns
+            the updates after the position that `next_cursor` marks. Send
+            `updates_after` or `cursor`, not both.
+          schema:
+            type: string
       responses:
         "200":
           description: The transactions with a disposition or note update.
@@ -512,11 +526,17 @@ components:
       description: >-
         The request is not valid. The `code` is one of:
 
-        - `UPDATES_AFTER_REQUIRED`: the request has no `updates_after`
-        parameter, or its value is empty.
+        - `UPDATES_AFTER_REQUIRED`: `updates_after` and `cursor` are both
+        missing or empty.
 
         - `TIMESTAMP_INVALID`: `updates_after` is not a valid RFC 3339
         timestamp.
+
+        - `CURSOR_INVALID`: `cursor` is not valid. Send a `next_cursor` value
+        from a previous response.
+
+        - `CURSOR_AND_UPDATES_AFTER_PROVIDED`: `updates_after` and `cursor` both
+        have a value.
       content:
         application/vnd.maxmind.com-error+json:
           schema: