Appearance
API reference
The whole API is 18 operations. Every operation has its own page in the sidebar. This page is what is true of all of them.
Endpoint
Every path below is relative to the base URL:
https://api.spooler.sh/v1The spoolersh/memspoold image serves the same API on http://localhost:8080/v1. What the /v1 segment promises is on compatibility.
Authentication
Every operation authenticates with an API key from the console, presented as a bearer token:
Authorization: Bearer <key>A missing or bad key fails with 401; a suspended account with 402; a blocked key with 403. Keys never travel in query strings.
Addressing
Every operation names one of your spools: /spools/{spool}/… (the quickstart uses default). Queue operations address /queues/{queue} under it. Ack, nack, release, fail, renew, recover, discard, and ack-and-send are spool-scoped — the token already names the queue, so a wrong queue is unrepresentable. Ack-and-send names the queue it sends to in the Spooler-Queue header; the lease names the one it acks from. Name rules are in limits.
Leases and handles
Two kinds of token exist, and neither is accepted where the other is expected.
A lease comes from a receive in Spooler-Lease: exclusive ownership of one delivery. No other receiver gets the message until the lease is settled or, on a queue with a lease timeout, it expires (Spooler-Lease-Expires-At; absent when the queue has none). Ack, nack, release, fail, renew, and ack-and-send present it back.
A handle is a reference to one delivery generation of a message: no ownership, no timeout. A send with handle=true returns one in Spooler-Handle; a message listing with handle=true includes a handle field on each message. Present it back in the Spooler-Handle request header: inspect reads the message by it, discard drops by it, and recover takes it for a failed message. When a handle goes stale (410) is in delivery.
Ids never act. A message id is for logs and correlation, and no operation takes one: a mistyped id can never reach a real message, and a handle always names the generation its holder saw. Every operation taking a token, inspect included, checks that — a stale listing costs a fresh listing, never an action on a delivery someone else took.
Discard is the one operation that takes either token, exactly one per call: with a lease it is a consumer's terminal drop, removing the delivered message and counting it as discarded rather than acked.
Bodies
A send's request body is the payload — raw application/octet-stream, Content-Length required (411 without it, chunked bodies included; an empty message is an explicit 0); its outcome comes back as headers, the id in Spooler-Message-Id and, when asked for, the handle in Spooler-Handle, with no body. A receive's or inspect's response body is the payload; message attributes ride Spooler-* response headers. Ack, nack, release, fail, renew, recover, discard, and inspect take no body: the token rides the Spooler-Lease or Spooler-Handle request header, the same header it was returned in. Ack-and-send takes both: the lease in the header, the new payload as the body. So the message operations are bytes and headers only; everything else is JSON in, JSON out. There is no envelope and no base64.
Spooler-* headers
Message attributes travel as Spooler-* headers. Each operation accepts only the headers it defines: any other fails with 400 kind unknown_header — a typo is refused, never silently ignored.
Durations are integers with the unit in the name (waitSeconds, Spooler-Delay-Seconds, leaseTimeoutSeconds); timestamps are RFC 3339 UTC.
Responses
200 carries a body — except a send's dedup hit, which answers in headers alone; 201 means created or appended (a send's id rides Spooler-Message-Id); 204 means done with nothing to say (an ack, a delete, an empty receive). Errors are JSON {"kind", "message", "details"} — match on the status, kind and details, see errors. 429 carries Retry-After (see limits); 503 means the spool is momentarily unavailable — retry.
Operations
All 18 operations:
Queues
GET /spools/{spool}/queues/{queue} | Describe a queue |
PUT /spools/{spool}/queues/{queue} | Create a queue |
PATCH /spools/{spool}/queues/{queue} | Update queue settings |
DELETE /spools/{spool}/queues/{queue} | Delete a queue |
GET /spools/{spool}/queues | List queues |
GET /spools/{spool}/stats | Get spool stats |
Messages
GET /spools/{spool}/queues/{queue}/messages | List messages |
POST /spools/{spool}/queues/{queue}/send | Send a message |
POST /spools/{spool}/ack-and-send | Acknowledge a message and send another |
POST /spools/{spool}/queues/{queue}/recv | Receive a message |
POST /spools/{spool}/ack | Acknowledge a processed message |
POST /spools/{spool}/nack | Negatively acknowledge a message |
POST /spools/{spool}/release | Release a message |
POST /spools/{spool}/fail | Fail a message |
POST /spools/{spool}/renew | Renew a lease |
POST /spools/{spool}/inspect | Inspect a message |
POST /spools/{spool}/recover | Recover a failed message |
POST /spools/{spool}/discard | Discard a message |