diff --git a/bundled/minfraud.yaml b/bundled/minfraud.yaml index ebfa7fc..5ccc37b 100644 --- a/bundled/minfraud.yaml +++ b/bundled/minfraud.yaml @@ -197,7 +197,10 @@ 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: @@ -205,11 +208,17 @@ paths: 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. diff --git a/components/minfraud-response.yaml b/components/minfraud-response.yaml index 4ef885a..fd19c33 100644 --- a/components/minfraud-response.yaml +++ b/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: diff --git a/examples/minfraud/disposition-bad-request.yaml b/examples/minfraud/disposition-bad-request.yaml index b44cd84..7c26d00 100644 --- a/examples/minfraud/disposition-bad-request.yaml +++ b/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. diff --git a/examples/minfraud/disposition-updates.yaml b/examples/minfraud/disposition-updates.yaml index 1f056d3..ef42957 100644 --- a/examples/minfraud/disposition-updates.yaml +++ b/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 diff --git a/specs/minfraud.yaml b/specs/minfraud.yaml index 86022d6..4a4c084 100644 --- a/specs/minfraud.yaml +++ b/specs/minfraud.yaml @@ -220,9 +220,14 @@ 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: @@ -230,15 +235,24 @@ paths: 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: