API reference

API reference #

Creating a queue #

Route #

/queues

Example: http://localhost:7532/queues

Request #

Method: POST

Header Content-Type: application/json

Payload, overview #

{
    "name": <queue name>,
    "driver": <driver name>,
    "attributes": {
        <read-write attributes>
    }
}

Response #

Header Content-Type: application/json

Payload, overview #

{
    "name": <queue name>,
    "driver": <driver name>,
    "attributes": {
        "read-only": <read-only attributes>,
        "read-write": <read-write attributes>
    }
}

Examples #

Example #1 #

Creating a memfifo queue limited to 8GB, request payload:

{
    "name": "emails",
    "driver": "memfifo",
    "attributes": {
        "max-bytes": 8589934592
    }
}

Response payload:

{
    "name": "emails",
    "driver": "memfifo",
    "attributes": {
        "read-only": {
            "bytes": 0,
            "size": 0
        },
        "read-write": {
            "max-bytes": 8589934592
        }
    }
}

Status codes #

  • 200 OK: If the queue is created successfully.
  • 400 Bad Request: If the sent data is invalid, or if a queue with the same name already exists.

Deleting a queue #

Route #

/queues/<queue name>

Example: http://localhost:7532/queues/emails

Request #

Method: DELETE

Status codes #

  • 200 OK: If the queue is deleted successfully. This also means all messages it was holding have either been deleted, or will be deleted soon (asynchronously).
  • 404 Not Found: If the queue could not be found, and therefore could not be deleted.

Retrieving all queues #

Route #

/queues

Example: http://localhost:7532/queues

Request #

Method: GET

Response #

Header Content-Type: application/json

Examples #

Example #1 #

Retrieving multiple memfifo queues, response payload:

[
    {
        "name": "emails",
        "driver": "memfifo",
        "attributes": {
            "read-only": {
                "bytes": 0,
                "size": 0
            },
            "read-write": {
                "max-bytes": 8589934592
            }
        }
    },
    {
        "name": "receipts",
        "driver": "memfifo",
        "attributes": {
            "read-only": {
                "bytes": 1312872,
                "size": 864
            },
            "read-write": {
                "max-bytes": 268435456
            }
        }
    },
]

Example #2 #

Retrieving all queues when there are no queues, response payload:

[]

Status codes #

  • 200 OK: Always.

Retrieving a single queue #

Route #

/queues/<queue name>

Example: http://localhost:7532/queues/receipts

Request #

Method: GET

Response #

Header Content-Type: application/json

Examples #

Example #1 #

Retrieving a single memfifo queue named receipts:

{
    "name": "receipts",
    "driver": "memfifo",
    "attributes": {
        "read-only": {
            "bytes": 1312872,
            "size": 864
        },
        "read-write": {
            "max-bytes": 268435456
        }
    }
}

Status codes #

  • 200 OK: If successful.
  • 404 Not Found: If the queue could not be found, and therefore could not be retrieved.

Submitting a message #

Route #

/queues/<queue name>/messages

Example: http://localhost:7532/queues/emails/messages

Request #

Method: POST

Header Content-Type: any (everything is supported)

Header Client-Id: This is a special header that must be supplied when performing this request. It identifies the system currently submitting this message. Its value must be a string.

Body: any sequence of bytes, up to 4 megabytes in length. This exact byte sequence will be returned when this message is read back from the queue.

Response #

Header Content-Type: application/json

Header Message-Id: This is an auto-generated string that identifies the newly submitted message. It is unique. When, at some point, this message is read from the queue, the same identifier will be returned, also as a header.

Body: If successful, the response will be the same as if a request to retrieve the queue had been performed. Basically, a JSON response representing the queue’s latest state, after the message has been submitted.

Status codes #

  • 200 OK: If successful.
  • 404 Not Found: If the queue could not be found, and therefore the message could not be submitted.

Reading a message #

Route #

/queues/<queue name>/messages

Example: http://localhost:7532/queues/emails/messages

Request #

Method: GET

Header Client-Id: This is a special header that must be supplied when performing this request. It identifies the system currently reading messages from this queue. Its value must be a string.

Response #

Header Content-Type: any (will be exactly the same Content-Type that was submitted)

Header Message-Id: Exactly the same Message-Id that was originally returned when the message was submitted.

Body: If successful, the response’s body contains the exact same byte sequence that was originally submitted as part of the message’s body. Up to 4 megabytes in length.

Status codes #

  • 200 OK: If successful.
  • 204 No Content: If the queue is empty.
  • 404 Not Found: If the queue could not be found, and therefore no messages could be read from it.

Made with love and a lot of coffee in Porto Alegre, Brazil
Powered by   openSUSE   Go   Clojure   GNU Emacs   Hugo