Skip to main content

Committing Cursors

POST /api/subscriptions/{subscriptionId}/cursors

Request​

Cursors can be committed by making a POST request to the subscription's cursor resource /api/subscriptions/{subscriptionId}/cursors:

note

Please be aware that the X-Mambu-StreamId header is required when committing a cursor. The value should be the same as the X-Mambu-StreamId header you receive when opening a stream of events. Also, each client can only commit batches that it has received. This is unchanged from V1.

Sample Request

curl -v -X POST "https://TENANT_NAME.mambu.com/api/subscriptions/0691160a-b519-4595-b85c-a400fc73e963/cursors"\
  -H "X-Mambu-StreamId: 93ae5174-b863-4f8f-ba33-d274854d1f3d" \
  -H "Content-type: application/json" \
  -H "Accept: application/vnd.mambu.v2+json" \
  -d

Body Parameter

{
  "items": [
    {
      "partition": "shardId-000000000000",
      "offset": "49673591198887640830612221074728717584752617270261317634",
      "event_type": "mrn.event.TENANT_NAME.streamingapi.client_approved",
      "cursor_token": "3b0123a1-532e-4dd3-81ec-aa71a2dd443f"
    }
  ]
}
note

Field names are unchanged from V1 (partition, offset, event_type, cursor_token) — only the partition and offset value formats changed. See Differences Between Streaming API V1 and V2.

Response​

The possible successful responses for a commit are:

  • 204: Cursors were successfully committed and offset was increased.
  • 200: Cursors were committed but at least one of the cursors didn't increase the offset, since it was less than or equal to the already committed one. The response body includes a list of cursors and the result (committed or outdated) of each.

The timeout for commit is controlled by the commit_timeout query parameter on the events stream request (see Event Streaming Configurations), up to a maximum of 60 seconds. If you open the stream, read data, and don't commit anything before the timeout elapses, the stream connection will be closed from the Mambu side. If there are no events available to send and you get only empty batches, there is no need to commit — Mambu will only close the connection if there is uncommitted data and no commits happen within the timeout.

Needs confirmation

The default value of commit_timeout when the query parameter isn't specified has not been confirmed — flagged during review as possibly 30 seconds rather than 60.

If the connection is closed for any reason, the client still has the same amount of time to commit the events it received from the moment the events were sent. After that, the session is considered closed and it's no longer possible to commit with that X-Mambu-StreamId. If the commit was not made, the next time you start reading from a subscription you will get data from the last point of your commit — you will receive the events you haven't committed again and will need to deduplicate.

Last updated on