This section describes the REST API provided by the Apache Qpid Broker for Java. The REST API is intended for use by developers who wish to automate the management or monitoring of the Qpid Broker. It is also very useful for adhoc monitoring on the command line using tools such as curl. The REST API provides access to all of the Broker's entities using hierarchical paths expressed by the URI. Responses are returned in JSON format. The GET method request retrieves information about an object, the DELETE method requests the removal of one, and the PUT or POST methods perform updates or create new objects. The POST method is also used to invoke operations. The REST API is versioned with the version number embedded within the URI. The general form of the URI is /api/<version> where <version> is a dot separated major and minor model version prefixed with "v", for example, "v6.1" (without the quotation marks). For convenience the alias latest (/api/latest) signifies the latest supported version. There are also some ancillary services under URI /service used for authentication and logout.

REST API documentation is available on-line from any Broker at location /apidocs. It is also linked from the menu of the Web Management Console.

Before you can use the REST API, you must authenticate. Authentication decisions are made by the authentication provider associated with HTTP port on which you connect. You may authenticate using SASL (/service/sasl) or HTTP Basic Authentication. The latter is convienent when using tools such as curl on the command line. This is illustrated in the examples below. For SASL authentication use a GET request to /service/sasl to get a list of supported SASL mechanisms, and use PUT to the same URL to perform the SASL negotiation. It is possible to end an authenticated session using /service/logout.

Methods PUT or POST can be used to create ConfiguredObject. ConfiguredObject can be created by submitting PUT request against ConfiguredObject full URI (the one ending with configured object name) or by submitting PUT/POST request against parent URI. The request encoding should be json (application/json) and request body should contain attributes values in json format. On successful completion of operation a response should be returned having response status code set to 201 and response header "Location" set to ConfiguredObject full URI. If object with a such name/id already exist and POST/PUT requests is made against parent URI, an error response should be returned having response code 409 (conflict) and body containing the json with the reason of operation failure. If object with a such name/id already exist and and PUT request is made against ConfiguredObject full URI, then ConfiguredObject update should be performed and http status code 200 should be returned. If ConfiguredObject cannot be created because of validation failure(s) the response should have http status code set 422 (Unprocessible Entity) and body should contain json with the reason of operation failure. On any other failure to create ConfiguredObject the response should have status code set to 400 (Bad Request) and payload should contain a json with error explaining the exact reason of failure. To create Queue with name "my-queue" on a virtual host with name "vh" (which is contained within virtual host node with name "vhn") either of the following requests should be made: PUT /api/latest/queue/vhn/vh HTTP/1.1 POST /api/latest/queue/vhn/vh HTTP/1.1 PUT /api/latest/queue/vhn/vh/my-queue HTTP/1.1 Response code 201 should be returned on successful queue creation. Response header "Location" should be set to "/api/latest/queue/test/my-queue". If queue with name "my-queue" already exists and either of 2 first requests above were used, an error response with response code 409 (conflict) and body containing json with message that queue exists should be returned. If queue with name "my-queue" exists and last request is used, then Queue update should occur.

Methods PUT or POST can be used to update ConfiguredObject. ConfiguredObject can be updated by submitting PUT or POST request against ConfiguredObject full URI (the one ending with configured object name). The request encoding should be json (application/json) and request body should contain a ConfiguredObject json (with all or only modified attributes). On successful completion of operation a response code 200 should be returned. If ConfiguredObject does not exists and PUT method is used, such object should be created (201 response will be returned in this case). If ConfiguredObject does not exists and POST method is used, an error response should be returned having response status code 404 and payload with json explaining the problem. If any error occur on update, a response with response code 400 or 422 or 404 should be sent back to the client containing json body with error details. To update Queue with name "my-queue" on a virtual host with name "vh" (contained in virtual host node with name "vhn") either of the following requests can be made: POST /api/latest/queue/vhn/vh/my-queue HTTP/1.1 POST /api/latest/queue/vhn/vh/my-queue HTTP/1.1

Method DELETE can be used to delete ConfiguredObject. Alternatively, ConfiguredObject can be deleted with update request having desiredState attribute set to value "DELETED". POST or PUT methods can be used in this case. On successful completion of operation a response code 200 should be returned. With DELETE method object ConfiguredObject in following ways: by submitting DELETE request using ConfiguredObject full URI (the one ending with configured object name) by submitting DELETE request using parent URI and providing parameters having the same names as children attributes, for example, id, name, etc. Multiple children can be deleted in a such way. Many "id" parameters can be specified in such requests. Only children with matching attribute values will be deleted. To delete Queue with name "my-queue" on a virtual host with name "vh" (contained in virtual host node with name "vhn") either of the following requests can be made: DELETE /api/latest/queue/vhn/vh/my-queue HTTP/1.1 DELETE /api/latest/queue/vhn/vh?name=my-queue HTTP/1.1 DELETE /api/latest/queue/vhn/vh?id=real-queue-id HTTP/1.1

Method GET is used to retrieve ConfiguredObject attributes values and children hierarchy. A particular ConfiguredObject details can be retrieved using full ConfiguredObject URI (the one ending with configured object name) A collection of ConfiguredObjects can be retrieved using parent URI. Request parameters (having the same name as attributes) can be used to filter the returned configured objects. The REST URI (/api/latest/>category</*) are hierarchical. It is permitted to replace REST URI elements with an "asterisks" in GET requests to denote all object of a particular type. Additionally, trailing object type in the URL hierarchy can be omitted. In this case GET request will return all of the object underneath of the current object. For example, for binding URL http://localhost:8080/api/latest/binding/<vhost node>/<vhost>/<exchange>/<queue>/<binding> replacing of <exchange> with "asterisks" (http://localhost:8080/api/<ver>/binding/<vhost node>/<vhost>/*/<queue>/<binding>) will result in the GET response containing the list of bindings for all of the exchanges in the virtualhost having the given name and given queue. If <binding> and <queue> are omitted in binding REST URL (http://localhost:8080/api/<ver>/binding/<vhost node>/<vhost>/<exchangename>) the GET request will result in returning all bindings for all queues for the given exchange in the virtual host. Additional parameters supported in GET requests: depth To restrict the depth of hierarchy of configured objects to return in response actuals If set to "true" attribute actual values are returned instead of effective includeSysContext If set to "true" all system context variables are returned inheritedActuals If set to "true" actual values for all inherited context is returned. oversize Sets the maximum length for values of over-sized attributes to trim extractInitialConfig If set to "true", the returned json can be used as initial configuration.

Method POST is used to invoke Configured Objects operations. Some operations support parameters. Pass parameters using a JSON request body containing a map with a map entry for each parameter. To clear the queue with name "my-queue" on a virtual host with name "vh". POST api/latest/queue/vhn/vh/my-queue/clearQueue HTTP/1.1

Status code Description 200 REST request is successfully completed. This status code can be returned by update, delete and get requests. 201 New configured object is created. It is returned by REST PUT and POST requests for creation of configured objects. 400 REST request cannot be performed due to errors in request. It can be returned from create, update and delete requests. The details of a problem are provided in the response payload in json format. 401 The request requires user authentication 403 Execution of request is not allowed due to failure to authorize user operation. 404 The requested configured object cannot be found. This status code can be returned from POST update requests if configured object does not exist. The reason for the status code is provided in the response payload in json format. 409 The request can not be performed because its execution can create conflicts in the broker. This status code can be returned from POST/PUT create requests against parent URI if configured object with requested name or id already exists. The status code 409 can also be returned if removal or update of configured object can violate system integrity. The reason for the status code is provided in the response payload in json format. 422 The request can not be performed because provided information either incomplete or invalid. This status code can be returned from create or update requests. The reason for the status code is provided in the response payload in json format.

#create a durable queue curl --user admin -X PUT -d '{"durable":true}' http://localhost:8080/api/latest/queue/<vhostnode name>/<vhostname>/<queuename> #create a durable priority queue curl --user admin -X PUT -d '{"durable":true,"type":"priority"}' http://localhost:8080/api/latest/queue/<vhostnode name>/<vhostname>/<queuename> curl --user admin -X PUT -d '{}' http://localhost:8080/api/latest/binding/<vhostnode name>/<vhostname>/<exchangename>/<queue-name>/<binding-name> NOTE: These curl examples utilise unsecure HTTP transport. To use the examples it is first necessary enable Basic authentication for HTTP within the HTTP Management Configuration (it is off by default). For details see

The Broker supports Cross Origin Resource Sharing (CORS) to allow web management consoles other than the one embedded in the broker to use the REST API. This feature must be enabled by configuring the CORS Allow Origins and related attributes on the