REST and gRPC API

Kahuna exposes sequence operations through REST and gRPC.

REST API

All sequence REST APIs use POST.

Endpoint	Purpose
/v1/sequences/create	Create a persistent sequence.
/v1/sequences/update	Rewrite sequence parameters and start a new incarnation.
/v1/sequences/get	Read sequence metadata.
/v1/sequences/next	Allocate one value.
/v1/sequences/reserve	Allocate a contiguous range.
/v1/sequences/delete	Delete a sequence.

Create

curl -X POST https://localhost:8082/v1/sequences/create \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "orders",
    "initialValue": 0,
    "increment": 1,
    "maxValue": null,
    "blockSize": null,
    "durability": "Persistent"
  }'

Update

curl -X POST https://localhost:8082/v1/sequences/update \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "orders",
    "currentValue": 5000,
    "increment": 1,
    "blockSize": 100,
    "durability": "Persistent"
  }'

Use removeMaxValue: true or removeBlockSize: true to clear those optional settings. Omitting a field leaves the existing value unchanged.

Get

curl -X POST https://localhost:8082/v1/sequences/get \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "orders",
    "durability": "Persistent"
  }'

Next

curl -X POST https://localhost:8082/v1/sequences/next \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "orders",
    "idempotencyKey": "request-123",
    "durability": "Persistent"
  }'

Response allocation:

{
  "type": "Success",
  "allocation": {
    "name": "orders",
    "start": 1,
    "end": 1,
    "count": 1,
    "revision": 1
  },
  "revision": 1
}

Reserve

curl -X POST https://localhost:8082/v1/sequences/reserve \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "orders",
    "count": 100,
    "idempotencyKey": "batch-456",
    "durability": "Persistent"
  }'

Delete

curl -X POST https://localhost:8082/v1/sequences/delete \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "orders",
    "durability": "Persistent"
  }'

gRPC API

The gRPC service is named Sequencer:

service Sequencer {
  rpc CreateSequence (GrpcCreateSequenceRequest) returns (GrpcSequenceResponse);
  rpc UpdateSequence (GrpcUpdateSequenceRequest) returns (GrpcSequenceResponse);
  rpc GetSequence (GrpcGetSequenceRequest) returns (GrpcSequenceResponse);
  rpc NextSequenceValue (GrpcNextSequenceRequest) returns (GrpcSequenceAllocationResponse);
  rpc ReserveSequenceRange (GrpcReserveSequenceRangeRequest) returns (GrpcSequenceAllocationResponse);
  rpc DeleteSequence (GrpcDeleteSequenceRequest) returns (GrpcSequenceResponse);
}

Response Types

Type	Meaning
Success	The operation succeeded.
NotFound	The sequence does not exist.
AlreadyExists	Create was called for an existing sequence.
InvalidInput	The name or request parameters were invalid.
MaxValueExceeded	The requested allocation would exceed MaxValue.
MustRetry	The operation should be retried. Allocations also return this while a sequence update is waiting out the block lease.
Aborted	The operation was aborted.
Error	An unexpected error occurred.