RabbitMQ Management HTTP API

Introduction

Apart from this help page, all URIs will serve only resources of type application/json, and will require HTTP basic authentication (using the standard RabbitMQ user database). The default user is guest/guest.

Many URIs require the name of a virtual host as part of the path, since names only uniquely identify objects within a virtual host. As the default virtual host is called "/", this will need to be encoded as "%2F".

PUTing a resource creates it. The JSON object you upload must have certain mandatory keys (documented below) and may have optional keys. Other keys are ignored. Missing mandatory keys constitute an error.

Since bindings do not have names or IDs in AMQP we synthesise one based on all its properties. Since predicting this name is hard in the general case, you can also create bindings by POSTing to a factory URI. See the example below.

Many URIs return lists. Such URIs can have the query string parameters sort and sort_reverse added. sort allows you to select a primary field to sort by, and sort_reverse will reverse the sort order if set to true. The sort parameter can contain subfields separated by dots. This allows you to sort by a nested component of the listed items; it does not allow you to sort by more than one field. See the example below.

You can also restrict what information is returned per item with the columns parameter. This is a comma-separated list of subfields separated by dots. See the example below.

It is possible to disable the statistics in the GET requests and obtain just the basic information of every object. This reduces considerably the amount of data returned and the memory and resource consumption of each query in the system. For some monitoring and operation purposes, these queries are more appropiate. The query string parameter disable_stats set to true will achieve this.

Most of the GET queries return many fields per object. The second part of this guide covers those.

Examples

A few quick examples for Windows and Unix, using the command line tool curl:

• Get a list of vhosts:

  :: Windows
  C:\> curl -i -u guest:guest http://localhost:15672/api/vhosts
  
  # Unix
  $ curl -i -u guest:guest http://localhost:15672/api/vhosts
  
  HTTP/1.1 200 OK
  cache-control: no-cache
  content-length: 196
  content-security-policy: default-src 'self'
  content-type: application/json
  date: Mon, 02 Sep 2019 07:51:49 GMT
  server: Cowboy
  vary: accept, accept-encoding, origin
  
  [{"cluster_state":{"rabbit@localhost":"running"},"description":"Default virtual host" ... (remainder elided)

• Get a list of channels, fast publishers first, restricting the info items we get back:

  :: Windows
  C:\> curl -i -u guest:guest "http://localhost:15672/api/channels?sort=message_stats.publish_details.rate&sort_reverse=true&columns=name,message_stats.publish_details.rate,message_stats.deliver_get_details.rate"
  
  # Unix
  $ curl -i -u guest:guest 'http://localhost:15672/api/channels?sort=message_stats.publish_details.rate&sort_reverse=true&columns=name,message_stats.publish_details.rate,message_stats.deliver_get_details.rate'
  
  HTTP/1.1 200 OK
  cache-control: no-cache
  content-length: 2
  content-security-policy: default-src 'self'
  content-type: application/json
  date: Mon, 02 Sep 2019 07:54:35 GMT
  server: Cowboy
  vary: accept, accept-encoding, origin
  
  [{"message_stats":{"publish_details":{"rate" ... (remainder elided)

• Create a new vhost:

  :: Windows
  C:\> curl -i -u guest:guest -H "content-type:application/json" ^
        -XPUT http://localhost:15672/api/vhosts/foo
  
  # Unix
  $ curl -i -u guest:guest -H "content-type:application/json" \
     -XPUT http://localhost:15672/api/vhosts/foo
  
  HTTP/1.1 201 Created
  content-length: 0
  content-security-policy: default-src 'self'
  date: Mon, 02 Sep 2019 07:55:24 GMT
  server: Cowboy
  vary: accept, accept-encoding, origin

  Note: you must specify application/json as the mime type.

  Note: the name of the object is not needed in the JSON object uploaded, since it is in the URI. As a virtual host has no properties apart from its name, this means you do not need to specify a body at all!

• Create a new exchange in the default virtual host:

  :: Windows
  C:\> curl -i -u guest:guest -H "content-type:application/json" ^
         -XPUT -d"{""type"":""direct"",""durable"":true}" ^
         http://localhost:15672/api/exchanges/%2F/my-new-exchange
  
  # Unix
  $ curl -i -u guest:guest -H "content-type:application/json" \
      -XPUT -d'{"type":"direct","durable":true}' \
      http://localhost:15672/api/exchanges/%2F/my-new-exchange
  
  HTTP/1.1 201 Created
  content-length: 0
  content-security-policy: default-src 'self'
  date: Mon, 02 Sep 2019 07:56:06 GMT
  server: Cowboy
  vary: accept, accept-encoding, origin

  Note: we never return a body in response to a PUT or DELETE, unless it fails.

• And delete it again:

  :: Windows
  C:\> curl -i -u guest:guest -H "content-type:application/json" ^
         -XDELETE http://localhost:15672/api/exchanges/%2F/my-new-exchange
  
  # Unix
  $ curl -i -u guest:guest -H "content-type:application/json" \
      -XDELETE http://localhost:15672/api/exchanges/%2F/my-new-exchange
  
  HTTP/1.1 204 No Content
  content-security-policy: default-src 'self'
  date: Mon, 02 Sep 2019 07:56:59 GMT
  server: Cowboy
  vary: accept, accept-encoding, origin

Reference

{"type":"direct","auto_delete":false,"durable":true,"internal":false,"arguments":{}}

{"properties":{},"routing_key":"my key","payload":"my body","payload_encoding":"string"}

{"routed": true}

{"auto_delete":false,"durable":true,"arguments":{},"node":"rabbit@smacmullen"}

{"action":"sync"}

{"count":5,"ackmode":"ack_requeue_true","encoding":"auto","truncate":50000}

{"routing_key":"my_routing_key", "arguments":{"x-arg": "value"}}

{"routing_key":"my_routing_key", "arguments":{"x-arg": "value"}}

{"description":"virtual host description", "tags":"accounts,production"}

{"tracing":true}

{"users" : ["user1", "user2", "user3"]}

{"password":"secret","tags":"administrator"}

{"password_hash":"2lmoth8l4H0DViLaK9Fxi6l9ds8=", "tags":["administrator"]}

{"value": 100}

curl -4u 'guest:guest' -H 'content-type:application/json' -X PUT localhost:15672/api/user-limits/guest/max-connections -d '{"value": 50}'

{"configure":".*","write":".*","read":".*"}

{"exchange":"amq.topic","write":"^a","read":".*"}

{"vhost": "/","component":"federation","name":"local_username","value":"guest"}

{"name":"user_vhost_mapping","value":{"guest":"/","rabbit":"warren"}}

{"pattern":"^amq.", "definition": {"federation-upstream-set":"all"}, "priority":0, "apply-to": "all"}

{"pattern":"^amq.", "definition": {"expires":100}, "priority":0, "apply-to": "queues"}

{"value": 100}

curl -4u 'guest:guest' -H 'content-type:application/json' -X PUT localhost:15672/api/vhost-limits/my-vhost/max-connections -d '{"value": 50}'

{"oauth_enabled":"boolean", "oauth_client_id":"string", "oauth_provider_url":"string"}

curl -4u 'guest:guest' -XPOST localhost:15672/api/rebalance/queues/

HTTP API Stats

Most of the GET requests you can issue to the HTTP API return JSON objects with a large number of keys. While a few of these keys represent things you set yourself in a PUT request or AMQP command (e.g. queue durability or arguments), most of them represent statistics to do with the object in question. This page attempts to document them.

It should be read in conjunction with the manual page for rabbitmqctl (see your installation if on Unix / Linux, or the RabbitMQ website for the latest version). Any field which can be returned by a command of the form rabbitmqctl list_something will also be returned in the equivalent part of the HTTP API, so all those keys are not documented here. However, the HTTP API also adds a lot of extra fields which are not available in rabbitmqctl.

_details objects

Many fields represent a count of some kind: queue length, messages acknowledged, bytes received and so on. Such absolute counts returned by the HTTP API will often have a corresponding _details object which offers information on how this count has changed. So for example, from a queue:

    "messages": 123619,
    "messages_details": {
      "avg": 41206.333333333336,
      "avg_rate": 1030.1583333333333,
      "rate": 24723.8,
      "samples": [
        {
          "sample": 123619,
          "timestamp": 1400680560000
        },
        {
          "sample": 0,
          "timestamp": 1400680500000
        },
        {
          "sample": 0,
          "timestamp": 1400680440000
        }
      ]
    }

Here we have a messages count (the total messages in the queue), with some additional data:

avg, avg_rate and samples will only appear if you request a specific time period by appending query parameters to the URL. To do this you need to set an age and an increment for the samples you want. The end of the range returned will always correspond to the present.

Different types of data take different query parameters to return samples, as in the following table. You can specify more than one set of parameters if the resource you are requesting can generate more than one type of sample (for example, queues can return message rates and queue lengths).

For example, appending ?lengths_age=3600&lengths_incr=60 will return the last hour's data on queue lengths, with a sample for every minute.

message_stats objects

Many objects (including queues, exchanges and channels) will return counts of messages passing through them. These are included in a message_stats object (which in turn will contain _details objects for each count, as described above).

These can contain:

Only fields for which some activity has taken place will appear.

Detailed message stats objects

In addition, queues, exchanges and channels can return a breakdown of message stats for each of their neighbours (i.e. adjacent objects in the chain: channel -> exchange -> queue -> channel). This will only happen if the rates_mode configuration item has been switched to detailed from its default of basic.

As this possibly constitutes a large quantity of data, it is also only returned when querying a single channel, queue or exchange rather than a list. Note also that the default sample retention policy means that these detailed message stats do not retain historical data for more than a few seconds.

The detailed message stats objects have different names depending on where they are (documented below). Each set of detailed stats consists of a list of objects with two fields, one identifying the partner object and one stats which is a message_stats object as described above.

For example, from a queue:

  "incoming": [
    {
      "stats": {
        "publish": 352593,
        "publish_details": {
          "rate": 100.2
        }
      },
      "exchange": {
        "name": "my-exchange",
        "vhost": "/"
      }
    }
    {
      "stats": {
        "publish": 543784,
        "publish_details": {
          "rate": 54.6
        }
      },
      "exchange": {
        "name": "amq.topic",
        "vhost": "/"
      }
    }
  ],

This queue is currently receiving messages from two exchanges: 100.2 msg/s from "my-exchange" and 54.6 msg/s from "amq.topic".

/api/overview

This has the following fields:

/api/nodes

This has the following fields:

/api/nodes/(name)

All of the above, plus:

/api/connections

/api/connections/(name)

See documentation for rabbitmqctl list_connections. No additional fields, although pid is replaced by node.

Note also that while non-AMQP connections will appear in this list (unlike rabbitmqctl list_connections), they will omit many of the connection-level statistics.

/api/connections/(name)/channels

/api/channels

See documentation for rabbitmqctl list_channels, with pid replaced by node, plus:

/api/channels/(name)

All the above, plus

/api/exchanges

/api/exchanges/(vhost)

See documentation for rabbitmqctl list_exchanges, plus:

/api/exchanges/(vhost)/(name)

All the above, plus:

/api/queues

/api/queues/(vhost)

See documentation for rabbitmqctl list_queues, with all references to pids replaced by nodes plus:

/api/queues/(vhost)/(name)

All the above, plus:

/api/vhosts/

/api/vhosts/(name)

All the fields from rabbitmqctl list_vhosts (i.e. name and tracing) plus: