6.3. REST API

6.3. REST API
Prev	Chapter 6. Management Channels	Next

6.3.1. Introduction

This section describes the REST API provided by the Apache Qpid Broker-J. The REST API is intended for use by developers who wish to automate the management or monitoring of the 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.

6.3.2. REST API documentation

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.

6.3.3. Authentication

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.

6.3.4. Configured Object creation

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.

Example 6.1. Examples of REST calls for Queue creation

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.

6.3.5. Configured Object update

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.

Example 6.2. Examples of REST calls for Queue update

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

6.3.6. Configured Object deletion

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.

Example 6.3. Examples of REST calls for Queue deletion

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

6.3.7. Retrieving Configured Object details

Method GET is used to retrieve an object's attributes values and statistics.

To retrieve a single object, use its full URI. For instance, to retrieve a single queue:

GET /api/latest/queue/vhn/vh/my-queue

To retrieve all objects beneath a parent, pass the parent's URI. For instance, to retrieve all queues beneath the virtualhost called vh. A collection will be returned.

GET /api/latest/queue/vhn/vh

Request parameters (with the same name as an attribute) are used to filter the returned collection. For instance, to filter those queues of type standard:

GET /api/latest/queue/vhn/vh?type=standard

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
excludeInheritedContext: If set to "false" the inherited context is included from the object's ancestors. Default is true.
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.

6.3.8. Configured Object operations

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.

Example 6.4. Example REST call invoking the operation clear queue

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

6.3.9. HTTP status codes returned by REST interfaces

Table 6.1. HTTP status codes returned by REST interfaces

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.

6.3.10. Examples of REST requests with curl

Example 6.5. Examples of queue creation using curl (authenticating as user admin):

#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>

NOTE: These curl examples utilise an unsecured 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 Section 7.15, “HTTP Plugin”

6.3.11. Query API

6.3.11.1. Introduction

The Qpid Broker-J provides a powerful feature called the Query API. This allows the retrieval of the existing configured objects attributes satisfying user-provided queries.

Developers and operators can use this feature to monitor the Broker. For example, using Query API one can find all queues with queue depth exceeding some limit or existing connections made from a particular location(s).

6.3.11.2. Query API Overview

When using the Query API one specifies the category of the object to query, a list of attributes to return in the result set, an optional where clause, expressed as a predicate, that determines the filtering criteria, ordering, and limit/offset. The features should be readily recognisable to anyone who has has familiarity with SQL.

Queries associate with either the broker as a whole, or an individual virtualhost. Queries associated with the Broker can query any object within the Broker. Queries associated with a virtualhost are limited to the objects of the virtualhost itself. For instance a queue query associated with a virtualhost queries only the queues belonging to that virtualhost. On the other hand, a queue query associated with the Broker sees all the queues belonging on the entire Broker.

Table 6.2. Query API URLs

Query API URL	Description
/api/latest/querybroker/<configured object category name> /api/<version>/querybroker/<configured object category name>	Query API URL fragment to query the specified object type across the entire broker
/api/latest/queryvhost/<virtual host node name>/<virtual host name>/<configured object category name> /api/<version>/queryvhost/<virtual host node name>/<virtual host name>/<configured object category name>	Query API URL fragment to query the specified object type for a specific virtualhost

Query API URL

Description

/api/latest/querybroker/<configured object category name>

/api/<version>/querybroker/<configured object category name>

Query API URL fragment to query the specified object type across the entire broker

/api/latest/queryvhost/<virtual host node name>/<virtual host name>/<configured object category name>

/api/<version>/queryvhost/<virtual host node name>/<virtual host name>/<configured object category name>

Query API URL fragment to query the specified object type for a specific virtualhost

The QueryAPI accepts select, where, orderBy, limit and offset request parameters.

Table 6.3. Query API request parameters

Parameter Name	Parameter Description
`select`	The `select` defines the columns of the result set. It is a comma-separated list of expressions. At its most simple, an expression can be the name of the attribute (e.g. `queueDepthBytes`), but more complex expressions are also supported. Columns within the result set are named. For expressions that are simple attribute names, the column names will follow the attributes themselves. By default, other expressions will have a no name. Column names can be overridden with an `AS` clause e.g. `now() AS currentDate`
`where`	The `where` provides a boolean expression defining the result set filtering. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax and is similar to selector expressions in JMS e.g. `queueDepthBytes > 16384 AND name like '%flow_queue'`.
`orderBy`	Ordering conditions; the syntax of the expression is based on a subset of the SQL92 ordering expression syntax. Similar to ordering expressions in SQL, one can specify in ordering expression attributes names, sub-expressions or indexes (starting from 1) of attributes or expressions specified in select.
`limit`	The maximum number of results to provide starting from given offset.
`offset`	An offset in results (default is 0) to provide results from.

Example 6.6. Example of a Query API request to retrieve queue names and depths.

GET api/latest/querybroker/queue?select=name,queueDepthBytes,queueDepthMessages&where=queueDepthBytes>0&orderBy=1 desc,2 desc&offset=0&limit=100 HTTP/1.1

6.3.11.3. Query API Results

The Query API returns a JSON response. The response contains the following:

headers: ordered list of result set column names derived from the select clause. Note that anonymous expressions (that is, those expressed without an AS) will have empty column name.
results: two dimensional array containing the result-set
total: The total number of results matching the where criteria.

Example 6.7. Example of Query API call for queue names and depths.

GET api/latest/querybroker/queue?select=name,queueDepthBytes,queueDepthMessages&where=queueDepthBytes>0&orderBy=1 desc,2 desc&offset=0&limit=100 HTTP/1.1

{
    "headers" : [ "name", "queueDepthBytes", "queueDepthMessages" ],
    "results" : [ [ "foo", 312, 26], [ "bar", 300, 24 ] ],
    "total" : 2
}

Query API expressions

Expressions within the select, where and orderBy clauses can be comprised in the following manner. Expressions can be nested to arbitary depth. Parentheses allow for precedence to be explicitly denoted.

variable name which can be an attribute name e.g queueDepthBytes or a reference to a parent attribute $parent.name
literal e.g. 3 or 'foo'
functions - see below e.g. now() or to_string(createdDate, '%tm/%td/%ty', 'EST')
arithmetic operations e.g. 3 * 4 or to_string(now()) + name

The following functions are supported:

Table 6.4. Query API functions

Function Name	Function Description
`concat(obj[,obj..])`	concatenates the given objects into a string
`now()`	returns current date and time
`to_date(object)`	converts the first parameter, which must be a string. into a date. The string must be in ISO-8601 format e.g. `1970-01-01T10:00:00Z`.
`date_add(object, duration)`	adds the given ISO-8601 duration `duration` e.g. `P1D` or `-PT10H` to the date provided by the first parameter.
`to_string(object[, format[, timezone]])`	Converts given object into a string. If the format argument is present, it must be a Java Formatter compliant string e.g. `%f` or `%tY-%tm-%td`. The timezone argument is significant if the object is a Date. If the timezone argument is specified it must be a valid Java timezone name. The date is converted to the specified timezone before being formatted by the`format`. If the timezone is omitted `UTC` is assumed.

6.3.12. Cross Origin Resource Sharing (CORS)

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 Section 7.15, “HTTP Plugin”

Prev	Up	Next
6.2. Web Management Console	Home	6.4. Prometheus Metrics

Project

Messaging APIs

Servers and tools

Resources