http-api.md

HTTP API Reference

Table of Content

1. Queues & Namespaces
   1. POST /api/queues
   2. GET /api/queues
   3. GET /api/ns
   4. DELETE /api/ns/:ns
   5. GET /api/ns/:ns/queues
   6. DELETE /api/ns/:ns/queues/:queueName
2. Acknowledged Messages
   1. GET /api/ns/:ns/queues/:queueName/acknowledged-messages
   2. DELETE /api/ns/:ns/queues/:queueName/acknowledged-messages
   3. DELETE /api/ns/:ns/queues/:queueName/acknowledged-messages/:id
   4. POST /api/ns/:ns/queues/:queueName/acknowledged-messages/:id/requeue
3. Dead-lettered Messages
   1. GET /api/ns/:ns/queues/:queueName/dead-lettered-messages
   2. DELETE /api/ns/:ns/queues/:queueName/dead-lettered-messages
   3. DELETE /api/ns/:ns/queues/:queueName/dead-lettered-messages/:id
   4. POST /api/ns/:ns/queues/:queueName/dead-lettered-messages/:id/requeue
4. Pending Messages
   1. GET /api/ns/:ns/queues/:queueName/pending-messages
   2. DELETE /api/ns/:ns/queues/:queueName/pending-messages
   3. DELETE /api/ns/:ns/queues/:queueName/pending-messages/:id
5. Scheduled Messages
   1. GET /api/main/scheduled-messages
   2. DELETE /api/main/scheduled-messages
   3. DELETE /api/main/scheduled-messages/:id
6. Queue Rate limiting
   1. POST /api/ns/:ns/queues/:queueName/rate-limit
   2. GET /api/ns/:ns/queues/:queueName/rate-limit
   3. DELETE /api/ns/:ns/queues/:queueName/rate-limit
7. Fanout Exchanges
   1. GET /api/exchanges
   2. POST /api/exchanges
   3. DELETE /api/exchanges/:exchangeName
   4. GET /api/exchanges/:exchangeName/queues
   5. POST /api/exchanges/:exchangeName/bind
   6. POST /api/exchanges/:exchangeName/unbind

Queues

POST /api/queues

JSON Body properties

• name (string): Required. Queue name.
• ns (string): Optional. Queue namespace.
• type (number): Required Queue type.

Example:

{
   "name": "my-queue",
   "type": 0
}

Response Body

{
   "queue": {
      "name": "my-queue",
      "ns": "default"
   },
   "settings": {
      "priorityQueuing": false,
      "type": 0,
      "rateLimit": null,
      "exchange":null
   }
}

GET /api/queues

Response body

{
   "data": [
      {
         "ns": "my-application",
         "name": "notifications"
      },
      {
         "ns": "my-application",
         "name": "orders"
      },
      {
         "ns": "my-application",
         "name": "confirmation_emails"
      }
   ]
}

GET /api/ns

Response body

{
    "data": [
        "namespace_a",
        "namespace_b",
        "testing"
   ]
}

DELETE /api/ns/:ns

Path parameters

• ns (string): Required. Namespace.

Response Body

204 No Content

GET /api/ns/:ns/queues

Path parameters

• ns (string): Required. Namespace.

Response Body

{
   "data": [
      {
         "ns": "my-app-namespace",
         "name": "notifications"
      },
      {
         "ns": "my-app-namespace",
         "name": "orders"
      },
      {
         "ns": "my-app-namespace",
         "name": "confirmation_emails"
      }
   ]
}

DELETE /api/ns/:ns/queues/:queueName

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

Response Body

204 No Content

Acknowledged Messages

GET /api/ns/:ns/queues/:queueName/acknowledged-messages

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

Query parameters

• skip (number): Optional. Offset from where messages should be taken. Starts from 0.
• take (number): Optional. Max number of messages that should be taken. Starts from 1.

Response Body

{
   "data": {
      "total": 1,
      "items": [
         {
            "sequenceId": 0,
            "message": {
               "body": {
                  "hello": "world"
               },
               "priority": null,
               "scheduledCron": null,
               "scheduledDelay": null,
               "scheduledRepeatPeriod": null,
               "scheduledRepeat": 0,
               "scheduledCronFired": false,
               "attempts": 0,
               "scheduledRepeatCount": 0,
               "delayed": false,
               "expired": false,
               "queue": {
                  "ns": "my-application",
                  "name": "test_queue"
               },
               "createdAt": 1635702165317,
               "publishedAt": 1737595989746,
               "scheduledAt": null,
               "uuid": "9e7b8046-200c-48de-aa9f-2caf0a172a83",
               "ttl": 0,
               "retryDelay": 0,
               "retryThreshold": 3,
               "consumeTimeout": 0
            }
         }
      ]
   }
}

DELETE /api/ns/:ns/queues/:queueName/acknowledged-messages

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

Response Body

204 No Content

DELETE /api/ns/:ns/queues/:queueName/acknowledged-messages/:id

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.
• id (string): Required. Message ID.

Query parameters

• sequenceId (number): Required. Message sequence ID.

Response Body

204 No Content

POST /api/ns/:ns/queues/:queueName/acknowledged-messages/:id/requeue

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.
• id (string): Required. Message ID.

Query parameters

• sequenceId (number): Required. Message sequence ID.

Response Body

204 No Content

Dead-lettered Messages

GET /api/ns/:ns/queues/:queueName/dead-lettered-messages

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

Query parameters

• skip (number): Optional. Offset from where messages should be taken. Starts from 0.
• take (number): Optional. Max number of messages that should be taken. Starts from 1.

Response Body

{
   "data": {
      "total": 1,
      "items": [
         {
            "sequenceId": 0,
            "message": {
               "body": { "hello": "world" },
               "priority": null,
               "scheduledCron": null,
               "scheduledDelay": null,
               "scheduledRepeatPeriod": null,
               "scheduledRepeat": 0,
               "scheduledCronFired": false,
               "attempts": 2,
               "scheduledRepeatCount": 0,
               "delayed": false,
               "expired": false,
               "queue": {
                  "ns": "my-application",
                  "name": "test_queue"
               },
               "createdAt": 1635702165317,
               "publishedAt": 1737595989746,
               "scheduledAt": 1637523400376,
               "uuid": "9e7b8046-200c-48de-aa9f-2caf0a172a83",
               "ttl": 0,
               "retryDelay": 0,
               "retryThreshold": 3,
               "consumeTimeout": 0
            }
         }
      ]
   }
}

DELETE /api/ns/:ns/queues/:queueName/dead-lettered-messages

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

Response Body

204 No Content

DELETE /api/ns/:ns/queues/:queueName/dead-lettered-messages/:id

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.
• id (string): Required. Message ID.

Query parameters

• sequenceId (number): Required. Message sequence ID.

Response Body

204 No Content

POST /api/ns/:ns/queues/:queueName/dead-lettered-messages/:id/requeue

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.
• id (string): Required. Message ID.

Query parameters

• sequenceId (number): Required. Message sequence ID.
• priority (number): Optional. Message priority. When provided, the message will be re-queued with priority.

Response Body

204 No Content

Pending Messages

GET /api/ns/:ns/queues/:queueName/pending-messages

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

Query parameters

• skip (number): Optional. Offset from where messages should be taken. Starts from 0.
• take (number): Optional. Max number of messages that should be taken. Starts from 1.

Response Body

{
   "data": {
      "total": 1,
      "items": [
         {
            "sequenceId": 0,
            "message": {
               "body": { "hello": "world" },
               "priority": null,
               "scheduledCron": null,
               "scheduledDelay": null,
               "scheduledRepeatPeriod": null,
               "scheduledRepeat": 0,
               "scheduledCronFired": false,
               "attempts": 0,
               "scheduledRepeatCount": 0,
               "delayed": false,
               "expired": false,
               "queue": {
                  "ns": "my-application",
                  "name": "test_queue"
               },
               "createdAt": 1635702165317,
               "publishedAt": 1635702167654,
               "scheduledAt": null,
               "uuid": "9e7b8046-200c-48de-aa9f-2caf0a172a83",
               "ttl": 0,
               "retryDelay": 0,
               "retryThreshold": 3,
               "consumeTimeout": 0
            }
         }
      ]
   }
}

DELETE /api/ns/:ns/queues/:queueName/pending-messages

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

Response Body

204 No Content

DELETE /api/ns/:ns/queues/:queueName/pending-messages/:id

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.
• id (string): Required. Message ID.

Query parameters

• sequenceId (number): Required. Message sequence ID.

Response Body

204 No Content

Scheduled Messages

GET /api/main/scheduled-messages

Query parameters

• skip (number): Optional. Offset from where messages should be taken. Starts from 0.
• take (number): Optional. Max number of messages that should be taken. Starts from 1.

Response Body

{
   "data": {
      "total": 1,
      "items": [
         {
            "sequenceId": 0,
            "message": {
               "body": { "hello": "world" },
               "priority": null,
               "scheduledCron": null,
               "scheduledDelay": null,
               "scheduledRepeatPeriod": 10000,
               "scheduledRepeat": 6,
               "scheduledCronFired": false,
               "attempts": 0,
               "scheduledRepeatCount": 0,
               "delayed": false,
               "expired": false,
               "queue": {
                  "ns": "my-application",
                  "name": "test_queue"
               },
               "createdAt": 1635702165317,
               "publishedAt": null,
               "scheduledAt": 1635702163487,
               "uuid": "9e7b8046-200c-48de-aa9f-2caf0a172a83",
               "ttl": 0,
               "retryDelay": 0,
               "retryThreshold": 3,
               "consumeTimeout": 0
            }
         }
      ]
   }
}

DELETE /api/main/scheduled-messages

Path parameters

• queueName (string): Required. Queue name.

Response Body

204 No Content

DELETE /api/main/scheduled-messages/:id

Path parameters

• id (string): Required. Message ID.

Query parameters

• sequenceId (number): Required. Message sequence ID.

Response Body

204 No Content

Queue Rate Limiting

POST /api/ns/:ns/queues/:queueName/rate-limit

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

JSON Body properties

• limit (number): Required. The maximum number of messages within an interval.
• interval (number): Required. The timespan for limit in milliseconds.

Example:

{
   "interval": 10000,
   "limit": 15
}

Response Body

204 No Content

GET /api/ns/:ns/queues/:queueName/rate-limit

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

Response Body

If a rate limit exists:

{
   "data": {
      "interval": 10000,
      "limit": 15
   }
}

Otherwise:

{
   "data": null
}

DELETE /api/ns/:ns/queues/:queueName/rate-limit

Path parameters

• ns (string): Required. Queue namespace.
• queueName (string): Required. Queue name.

Response Body

204 No Content

Fanout Exchanges

GET /api/exchanges

Response body

{
   "data": [
      "my-exchange-1",
      "my-exchange-2"
   ]
}

POST /api/exchanges

JSON Body properties

• exchangeName (string): Required. Fanout exchange name.

Example:

{
   "exchangeName": "my-exchange-3"
}

Response Body

{
   "data": [
      "my-exchange-1",
      "my-exchange-2",
      "my-exchange-3"
   ]
}

DELETE /api/exchanges/:exchangeName

Response body

{
   "data": [
      "my-exchange-1",
      "my-exchange-2"
   ]
}

GET /api/exchanges/:exchangeName/queues

Response body

{
   "data": [
      {
         "ns": "my-application",
         "name": "notifications"
      }
   ]
}

POST /api/exchanges/:exchangeName/bind

JSON Body properties

• queue (object): Required.
  • name (string): Required. Queue name.
  • ns (string): Optional. Queue namespace.

Example:

{
   "queue": {
      "name": "orders",
      "ns": "my-application"
   }
}

Response Body

204 No Content

POST /api/exchanges/:exchangeName/unbind

JSON Body properties

• queue (object): Required.
  • name (string): Required. Queue name.
  • ns (string): Optional. Queue namespace.

Example:

{
   "queue": {
      "name": "orders",
      "ns": "my-application"
   }
}

Response Body

204 No Content