Apollo 1.0-beta4 Management API
Overview
Apollo's REST API runs on port 61680 or via SSL on port 61681. If your running an Apollo broker on your local machine, you could access the API at the following HTTP URLs:
http://localhost:61680
https://localhost:61681
For all of the rest of this document, we will be leaving off that part, since it is the same for every API call.
Authentication
The broker requires all requests against the management API to supply user credentials which have administration privileges.
The user credentials should be supplied using via HTTP basic authentication. Example:
$ curl -u "admin:password" http://localhost:61680/broker
JSON Representation
The API routes are intended to be access programmatically as JSON services but they also provide an HTML representation so that the API services can easily be browsed using a standard web browser.
You must either set the HTTP Accept
header to application/json
or
append .json
to the URL to get the JSON representation of the data.
Example:
$ curl -H "Accept: application/json" -u "admin:password" \
http://localhost:61680/broker
$ curl -u "admin:password" http://localhost:61680/broker.json
Working with Tabular Results
Many of the resource routes provided by the broker implement a selectable paged tabular interface. A good example of such a resource route is the connections list. It's route is:
/broker/connections
Example:
$ curl -u "admin:password" \
'http://localhost:61680/broker/connections.json'
Results in a Data Page :
{
"page":0,
"page_size":100,
"total_pages":1,
"total_rows":2,
"headers":[
"*"
],
"rows":[
{
"id":"4",
"state":"STARTED",
"state_since":1306848325102,
"read_counter":103,
"write_counter":239110628,
"transport":"tcp",
"protocol":"stomp",
"remote_address":"/127.0.0.1:61775",
"protocol_version":"1.0",
"user":"admin",
"waiting_on":"client request",
"subscription_count":1
},
{
"id":"5",
"state":"STARTED",
"state_since":1306848325102,
"read_counter":227739229,
"write_counter":113,
"transport":"tcp",
"protocol":"stomp",
"remote_address":"/127.0.0.1:61776",
"protocol_version":"1.0",
"user":"admin",
"waiting_on":"blocked sending to: org.apache.activemq.apollo.broker.Queue$$anon$1@13765e9b",
"subscription_count":0
}
]
}
{pygmentiz}
The `*` header field means the record was selected. To narrow down the selected fields you can add
multiple `f` query parameters to pick the fields you want to retrieve.
Example:
$ curl -u "admin:password" \
'http://localhost:61680/broker/connections.json?f=id&f=read_counter'
Results in :
{pygmentize:: js}
{
"page":0,
"page_size":100,
"total_pages":1,
"total_rows":2,
"headers":[
"id",
"read_counter"
],
"rows":[
[
"7",
110733109
],
[
"6",
103
]
]
}
{pygmentiz}
If you want to narrow down the records which get selected, you can set a `q`
query parameter to SQL 92 style where clause which uses the record's fields
to filter down the selected records.
For example to only view local connection, you would want to use a where
clause like `remote_address LIKE "/127.0.0.01:%"` which to execute with
`curl` you would run:
curl -u "admin:password" \
'http://localhost:61680/broker/connections.json?q=remote_address%20LIKE%20"/127.0.0.1:%"'
The records are paged. The default page size is 100, so only the first 100
records will be displayed. If you want to view subsequent results, you must
set the `p` query parameter to the page you wish to access. You can change
the page size by setting the `ps` query parameter.
The results are typically return in the order in which the records were original
created. If you want to retrieve them in a different order, use the `o` query
parameter to define the order in which they are returned. Example:
curl -u "admin:password" \
'http://localhost:61680/broker/connections.json?o=write_counter%20DESC&o=id'
### Broker Management
The route for managing the broker is:
/broker
Doing a GET against it will provide information about the broker's
* Version
* Running State
* Virtual Hosts
* Connectors
* Connections
Example:
$ curl -u "admin:password" \
http://localhost:61680/broker.json
Results in a [Broker Status](./api/apollo-dto/org/apache/activemq/apollo/dto/BrokerStatusDTO.html) :
{pygmentize:: js}
{
"version":"1.0-beta4",
"id":"default",
"state":"STARTED",
"state_since":1305388053086,
"current_time":1305388817653,
"virtual_hosts":["localhost"],
"connectors":[
"stomps",
"stomp"
],
"connections":[
{"id":24,"label":"/127.0.0.1:52603"},
{"id":25,"label":"/127.0.0.1:52604"}
],
}
Connector Management
The route for getting a tabular list of connectors is:
/broker/connectors
The route for managing a connector is:
/broker/connectors/:id
Example:
$ curl -u "admin:password"
http://localhost:61680/broker/connectors/stomp.json
Results in a Connector Status:
{
"id":"stomp",
"state":"STARTED",
"state_since":1305553109899,
"accepted":6,
"connected":2
}
To stop a connector send a POST to:
/broker/connectors/:id/action/stop
Example:
curl -X POST -u "admin:password" \
http://localhost:61680/broker/connectors/stomp/action/stop.json
To start a stopped a connector send a POST to:
/broker/connectors/:id/action/start
Example:
curl -X POST -u "admin:password" \
http://localhost:61680/broker/connectors/stomp/action/start.json
Connection Management
The route for getting a tabular list of connections is:
/broker/connections
The route for managing a single connection is:
/broker/connections/:id
Example:
$ curl -u "admin:password" \
http://localhost:61680/broker/connections/5.json
Results in a Connection Status:
{
"id":"5",
"state":"STARTED",
"state_since":1305553686946,
"read_counter":1401476017,
"write_counter":99,
"transport":"tcp",
"protocol":"stomp",
"remote_address":"/127.0.0.1:52638",
"protocol_version":"1.0",
"user":"admin",
"waiting_on":"client request",
"subscription_count":0
}
To shutdown a connection, send a DELETE to
/broker/connections/:id
or send a POST to:
/broker/connections/:id/action/delete
Example:
curl -X DELETE -u "admin:password" \
http://localhost:61680/broker/connections/5.json
Virtual Host Management
The route for managing a virtual host is:
/broker/virtual-hosts/:name
Where :name
is the id of a virtual host configured in the broker.
Example:
$ curl -u "admin:password" \
http://localhost:61680/broker/virtual-hosts/localhost.json
Results in a Virtual Host Status:
{
"id":"localhost",
"state":"STARTED",
"state_since":1305390871786,
"topics":[
"item.prices",
"inventory.level"
],
"queues":[
"orders.req",
"orders.res",
],
"store":true
}
Virtual Host Store Management
The route for managing a virtual host's Store is:
/broker/virtual-hosts/:name/store
Where :name
is the id of a virtual host configured in the broker.
Example:
$ curl -u "admin:password" \
http://localhost:61680/broker/virtual-hosts/localhost/store.json
Results in a Store Status:
{
"@class":"org.apache.activemq.apollo.broker.store.bdb.dto.BDBStoreStatusDTO",
"state":"STARTED",
"state_since":1305554120954,
"canceled_message_counter":87927,
"flushed_message_counter":28576,
"canceled_enqueue_counter":87927,
"flushed_enqueue_counter":28576,
"message_load_latency":{
"count":0,
"total":0,
"max":0,
"min":0
},
"flush_latency":{
"count":0,
"total":0,
"max":0,
"min":0
},
"journal_append_latency":null,
"index_update_latency":null,
"message_load_batch_size":{
"count":0,
"total":0,
"max":-2147483648,
"min":2147483647
},
"pending_stores":0
}
Queue Management
The route for getting a tabular list of queues is:
/broker/virtual-hosts/:name/queues
The route for managing a virtual host's Queue is:
/broker/virtual-hosts/:name/queues/:qid
Where :name
is the id of a virtual host configured in the broker and :qid
is the id
of the queue.
Example:
$ curl -u "admin:password" \
http://localhost:61680/broker/virtual-hosts/localhost/queues/orders.req.json
Results in a Queue Status:
{
"id":"orders.req",
"config":{
"id":null,
"unified":null,
"producer_buffer":null,
"queue_buffer":null,
"consumer_buffer":null,
"persistent":null,
"swap":null,
"swap_range_size":null,
"acl":null
},
"binding":{
"@class":"org.apache.activemq.apollo.dto.QueueDestinationDTO",
"path":[
"orders",
"req"
]
},
"metrics":{
"enqueue_item_counter":72292,
"enqueue_size_counter":79943846,
"enqueue_ts":1306433477839,
"dequeue_item_counter":72144,
"dequeue_size_counter":79780158,
"dequeue_ts":1306433477839,
"nack_item_counter":0,
"nack_size_counter":0,
"nack_ts":1306433476813,
"queue_size":163688,
"queue_items":148,
"swapped_in_size":0,
"swapped_in_items":0,
"swapping_in_size":0,
"swapping_out_size":0,
"swapped_in_size_max":32768,
"swap_out_item_counter":148,
"swap_out_size_counter":163688,
"swap_in_item_counter":0,
"swap_in_size_counter":0
},
"entries":[
],
"producers":[
],
"consumers":[
]
}
To delete a queue, send a DELETE to
/broker/virtual-hosts/:name/queues/:qid
or send a POST to:
/broker/virtual-hosts/:name/queues/:qid/action/delete
Example:
curl -X DELETE -u "admin:password" \
http://localhost:61680/broker/virtual-hosts/localhost/queues/orders.req.json
Topic Management
The route for getting a tabular list of queues is:
/broker/virtual-hosts/:name/topics
The route for managing a virtual host's Topic is:
/broker/virtual-hosts/:name/topics/:tid
Where :name
is the id of a virtual host configured in the broker and :tid
is the id
of the topic.
Example:
$ curl -u "admin:password" \
http://localhost:61680/broker/virtual-hosts/localhost/topics/item.prices.json
Results in a Topic Status:
{
"id":"item.prices",
"config":{
"id":null,
"slow_consumer_policy":null,
"acl":null
},
"producers":[
{
"kind":"connection",
"id":"3",
"label":"/127.0.0.1:52772"
}
],
"consumers":[
{
"kind":"connection",
"id":"4",
"label":"/127.0.0.1:52773"
}
],
"dsubs":[
"mysubname"
]
}
Durable Subscription Management
The route for getting a tabular list of durable subscriptions is:
/broker/virtual-hosts/:name/dsubs
The route for managing a virtual host's durable subscription is:
/broker/virtual-hosts/:name/dsubs/:sub
Where :name
is the id of a virtual host configured in the broker and :sub
is the id
of the durable subscription.
Example:
$ curl -u "admin:password" \
http://localhost:61680/broker/virtual-hosts/localhost/dsubs/mysub.json
Results in a Queue Status:
To delete a durable subscription, send a DELETE to
/broker/virtual-hosts/:name/dsubs/:sub
or send a POST to:
/broker/virtual-hosts/:name/dsubs/:sub/action/delete
Example:
curl -X DELETE -u "admin:password" \
http://localhost:61680/broker/virtual-hosts/localhost/dsubs/mysub.json
Getting the Broker's Configuration
To get current runtime configuration of the broker GET:
/broker/config/runtime
Example:
$ curl -u "admin:password" \
http://localhost:61680/broker/config/runtime.json
Results in a Broker Configuration:
{
"notes":"\n The default configuration with tls/ssl enabled.\n ",
"virtual_hosts":[{
"id":"apollo-a",
"enabled":null,
"host_names":["localhost"],
"store":{
"@class":"org.apache.activemq.apollo.broker.store.bdb.dto.BDBStoreDTO",
"flush_delay":null,
"directory":"/Users/chirino/opt/apollo-a/data",
"read_threads":null,
"zero_copy":null
},
"auto_create_destinations":null,
"purge_on_startup":null,
"topics":[],
"queues":[],
"dsubs":[],
"regroup_connections":null,
"acl":{
"connects":[
{"allow":"admins","deny":null,"kind":null}
]
},
"authentication":{
"enabled":false,
"domain":null,
"acl_principal_kinds":[],
"user_principal_kinds":[]
},
"router":null,
"log_category":null
}],
"connectors":[{
"id":"stomp",
"enabled":null,
"bind":"tcp://0.0.0.0:61613",
"protocol":null,
"connection_limit":2000,
"protocols":[],"acl":null
},{
"id":"stomps",
"enabled":null,
"bind":"tls://0.0.0.0:61614",
"protocol":null,
"connection_limit":2000,
"protocols":[],
"acl":null
}],
"client_address":null,
"key_storage":{
"file":"/opt/apollo-a/etc/keystore",
"password":null,
"key_password":null,
"store_type":null,
"trust_algorithm":null,
"key_algorithm":null
},
"acl":{
"admins":[{
"allow":"admins",
"deny":null,
"kind":null
}]
},
"web_admins":[{
"bind":"http://127.0.0.1:61680"
}],
"authentication":{
"enabled":null,
"domain":"apollo",
"acl_principal_kinds":[],
"user_principal_kinds":[]
},
"log_category":{
"console":"console",
"audit":"audit",
"connection":"connection",
"security":"security"
},
"sticky_dispatching":null
}
Aggregate Queue Statistics
You can get aggregate queue statistics at either the broker or virtual host level by using one of the following URL routes:
/broker/queue-metrics
/broker/virtual-hosts/:name/queue-metrics
Example:
$ curl -u "admin:password" \
http://localhost:61680/broker/queue-metrics.json
Results in an Aggregate of Queue Metrics:
{
"enqueue_item_counter":0,
"enqueue_size_counter":0,
"enqueue_ts":0,
"dequeue_item_counter":0,
"dequeue_size_counter":0,
"dequeue_ts":0,
"nack_item_counter":0,
"nack_size_counter":0,
"nack_ts":0,
"queue_size":0,
"queue_items":0,
"swapped_in_size":0,
"swapped_in_items":0,
"swapping_in_size":0,
"swapping_out_size":0,
"swapped_in_size_max":0,
"swap_out_item_counter":0,
"swap_out_size_counter":0,
"swap_in_item_counter":0,
"swap_in_size_counter":0,
"queues":0
}