You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by or...@apache.org on 2015/03/13 15:09:58 UTC
svn commit: r1666457 -
/qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
Author: orudyy
Date: Fri Mar 13 14:09:58 2015
New Revision: 1666457
URL: http://svn.apache.org/r1666457
Log:
QPID-6438: Update documentation for REST interfaces
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
Modified: qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml?rev=1666457&r1=1666456&r2=1666457&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml Fri Mar 13 14:09:58 2015
@@ -22,316 +22,481 @@
<section id="Java-Broker-Management-Channel-REST-API">
<title>REST API</title>
- <para> This section provides a brief overview of the REST interface, which can be used directly to
+ <para> This section provides a brief overview of the REST interfaces, which can be used directly to
monitor and manage the Broker instance.</para>
- <para>The REST interface support traditional REST model which uses the GET method requests to
+ <section id="Java-Broker-Management-Channel-REST-API-Introduction">
+ <title>Introduction</title>
+ <para>The REST interface support traditional REST model which uses the GET method requests to
retrieve the information about broker configured objects, DELETE method requests to delete the
configured object, PUT to create or update the configured object and POST to perform the
- configured objects updates not available with the PUT requests.</para>
- <para>The REST API is versioned with the version number built into the URL. The general form of
- the URL is <literal>/api/<version></literal>. For convenience the alias
- <literal>latest</literal> signifies the latest supported version. There are also some
- ancillary services prefixed by <literal>/service</literal>.</para>
+ configured objects updates and creation.</para>
+ <para>The REST API is versioned with the version number built into the URL. The general form of
+ the URL is <literal>/api/<version></literal> where <version> is a major model version prefixed with "v", for example, v3.
+ For convenience the alias <literal>latest</literal> (<literal>/api/latest</literal>) signifies the latest supported version.
+ There are also some ancillary services under URI <literal>/service</literal>.</para>
+ </section>
- <para>The table below lists the available REST services with brief description how they can be
- used.</para>
-
- <table>
- <title>Rest services</title>
- <tgroup cols="6">
- <thead>
- <row>
- <entry>REST Service URL</entry>
- <entry>Description</entry>
- <entry>GET</entry>
- <entry>PUT</entry>
- <entry>POST</entry>
- <entry>DELETE</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>/api/<ver>/broker</para>
- </entry>
- <entry>
- <para>Rest service to manage broker instance</para>
- </entry>
- <entry>
- <para>Retrieves the details of broker configuration</para>
- </entry>
- <entry>
- <para>Updates broker attributes</para>
- </entry>
- <entry>
- <para>Not implemented yet</para>
- </entry>
- <entry>
- <para>Not implemented yet</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/authenticationprovider</para>
- <para>/api/<ver>/authenticationprovider/<authentication provider
- name></para>
- </entry>
- <entry>Rest service to manage authentication providers on the broker</entry>
- <entry>Retrieves the details about authentication providers</entry>
- <entry>Creates or updates authentication providers</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes authentication providers</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/accesscontrolprovider</para>
- </entry>
- <entry>Rest service to manage access control providers</entry>
- <entry>Retrieves the details about access control providers</entry>
- <entry>Creates access control provider</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes access control provider(s)</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/user</para>
- <para>/api/<ver>/user/<authentication provider name>/<user
- name></para>
- </entry>
- <entry>Rest service to manage user account</entry>
- <entry>Retrieves the details about user account</entry>
- <entry>Creates user account, updates user password</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes user account</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/groupprovider</para>
- <para>/api/<ver>/groupprovider/<group provider name></para>
- </entry>
- <entry>Rest service to manage group providers</entry>
- <entry>Retrieves the details about group provider(s)</entry>
- <entry>Creates group provider</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes groups providers</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/group</para>
- <para>/api/<ver>/group/<group provider name>/<group name></para>
- </entry>
- <entry>Rest service to manage user group</entry>
- <entry>Retrieves the details about user group</entry>
- <entry>Creates group</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes group</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/groupmember</para>
- <para>/api/<ver>/groupmember/<group provider name >/<group
- name>/<user name></para>
- </entry>
- <entry>Rest service to manage group member(s)</entry>
- <entry>Retrieves the details about group member(s)</entry>
- <entry>Add user to group</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes user from group</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/port</para>
- <para>/api/<ver>/port/<port name></para>
- </entry>
- <entry>Rest service to manage broker ports(s)</entry>
- <entry>Retrieves the details about the broker port(s)</entry>
- <entry>Creates or updates port</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes ports</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/keystore</para>
- </entry>
- <entry>Rest service to manage KeyStores</entry>
- <entry>Retrieves the details about KeyStore</entry>
- <entry>Creates or updates KeyStore</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes KeyStore(s)</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/truststore</para>
- </entry>
- <entry>Rest service to manage TrustStore</entry>
- <entry>Retrieves the details about TrustStore</entry>
- <entry>Creates or updates TrustStore</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes TrustStore(s)</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/plugin</para>
- </entry>
- <entry>Rest service to manage plugins</entry>
- <entry>Retrieves the details about plugins</entry>
- <entry>Updates plugin attributes</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/virtualhostnode</para>
- <para>/api/<ver>/virtualhostnode/<virtualhostnode name></para>
- </entry>
- <entry>Rest service to manage virtualhost node(s)</entry>
- <entry>Retrieves the details about the virtualhost node(s)</entry>
- <entry>Creates/Updates virtualhost node</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes virtualhost node</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/virtualhost</para>
- <para>/api/<ver>/virtualhost/<virtualhostnode name>/<virtualhost
- name></para>
- </entry>
- <entry>Rest service to manage virtualhost(s)</entry>
- <entry>Retrieves the details about the virtualhost(s)</entry>
- <entry>Creates/Updates virtualhost</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes virtualhost</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/queue</para>
- <para>/api/<ver>/queue/<virtualhostnode name>/<virtualhost
- name>/<queue name></para>
- </entry>
- <entry>Rest service to manage queue(s)</entry>
- <entry>Retrieves the details about the queue(s)</entry>
- <entry>Creates queue</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes queue</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/exchange</para>
- <para>/api/<ver>/exchange/<virtualhostnode name>/<virtualhost
- name>/<exchange name></para>
- </entry>
- <entry>Rest service to manage exchange(s)</entry>
- <entry>Retrieves the details about the exchange(s)</entry>
- <entry>Creates exchange</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes exchange</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/binding</para>
- <para>/api/<ver>/binding/<virtualhostnode name>/<virtualhost
- name>/<exchange name>/<queue name>/<binding name></para>
- </entry>
- <entry>Rest service to manage binding(s)</entry>
- <entry>Retrieves the details about the binding(s)</entry>
- <entry>Binds a queue to an exchange</entry>
- <entry>Not implemented yet</entry>
- <entry>Deletes binding</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/connection</para>
- <para>/api/<ver>/connection/<virtualhostnode name>/<virtualhost
- name>/<connection name></para>
- </entry>
- <entry>Rest service to manage connection(s)</entry>
- <entry>Retrieves the details about the connection(s)</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- </row>
- <row>
- <entry>
- <para>/api/<ver>/session</para>
- <para>/api/<ver>/session/<virtualhostnode name>/<virtualhost
- name>/<connection name>/<session name></para>
- </entry>
- <entry>Rest service to manage session(s)</entry>
- <entry>Retrieves the details about the session(s)</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- </row>
- <row>
- <entry>
- <para>/service/message/<virtualhost name>/<queue name></para>
- </entry>
- <entry>Rest service to manage messages(s)</entry>
- <entry>Retrieves the details about the messages(s)</entry>
- <entry>Not implemented yet</entry>
- <entry>Copies, moves messages</entry>
- <entry>Deletes messages</entry>
- </row>
- <row>
- <entry>
- <para>/service/message-content/<virtualhost name>/<queue name></para>
- </entry>
- <entry>Rest service to retrieve message content</entry>
- <entry>Retrieves the message content</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- </row>
- <row>
- <entry>
- <para>/service/logrecords</para>
- </entry>
- <entry>Rest service to retrieve broker logs</entry>
- <entry>Retrieves the broker logs</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- </row>
- <row>
- <entry>
- <para>/service/sasl</para>
- </entry>
- <entry>Sasl authentication</entry>
- <entry>Retrieves user current authentication status and broker supported SASL
- mechanisms</entry>
- <entry>Authenticates user using supported SASL mechanisms</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- </row>
- <row>
- <entry>
- <para>/service/logout</para>
- </entry>
- <entry>Log outs</entry>
- <entry>Log outs user</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- <entry>Not implemented yet</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>The REST URLs are hierarchical. It is permitted to replace rest URL 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.</para>
- <para>For example, for binding URL <literal>http://localhost:8080/api/latest/binding/<vhost
- node>/<vhost>/<exchange>/<queue>/<binding></literal> replacing of
+ <section id="Java-Broker-Management-Channel-REST-API-URI">
+ <title>REST interfaces</title>
+ <para>The following REST interfaces are implemented on Qpid Broker</para>
+ <table>
+ <title>Rest services</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>REST Service URI</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/broker</para></listitem>
+ <listitem><para>/api/<version>/broker</para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages broker instance attributes and provides current values of Broker attributes and children</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/virtualhostnode</para></listitem>
+ <listitem><para>/api/<version>/virtualhostnode</para></listitem>
+ <listitem><para>/api/latest/virtualhostnode/<virtual host node name></para></listitem>
+ <listitem><para>/api/<version>/virtualhostnode/<virtual host node name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) Virtual Host Node(s) on Broker and provides current values of Virtual Host Node attributes and its children</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/virtualhost</para></listitem>
+ <listitem><para>/api/<version>/virtualhost</para></listitem>
+ <listitem><para>/api/latest/virtualhost/<virtual host node name></para></listitem>
+ <listitem><para>/api/<version>/virtualhost/<virtual host node name></para></listitem>
+ <listitem><para>/api/latest/virtualhost/<virtual host node name>/<virtual host name></para></listitem>
+ <listitem><para>/api/<version>/virtualhost/<virtual host node name>/<virtual host name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) Virtual Host on Virtual Host Node and provides current values of Virtual Host attributes and its children</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/queue</para></listitem>
+ <listitem><para>/api/<version>/queue</para></listitem>
+ <listitem><para>/api/latest/queue/<virtual host node name></para></listitem>
+ <listitem><para>/api/<version>/queue/<virtual host node name></para></listitem>
+ <listitem><para>/api/latest/queue/<virtual host node name>/<virtual host name></para></listitem>
+ <listitem><para>/api/<version>/queue/<virtual host node name>/<virtual host name></para></listitem>
+ <listitem><para>/api/latest/queue/<virtual host node name>/<virtual host name>/<queue name></para></listitem>
+ <listitem><para>/api/<version>/queue/<virtual host node name>/<virtual host name>/<queue name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) Queue(s) on Virtual Host and provides current values of Queue attributes and its children</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/exchange</para></listitem>
+ <listitem><para>/api/<version>/exchange</para></listitem>
+ <listitem><para>/api/latest/exchange/<virtual host node name></para></listitem>
+ <listitem><para>/api/<version>/exchange/<virtual host node name></para></listitem>
+ <listitem><para>/api/latest/exchange/<virtual host node name>/<virtual host name></para></listitem>
+ <listitem><para>/api/<version>/exchange/<virtual host node name>/<virtual host name></para></listitem>
+ <listitem><para>/api/latest/exchange/<virtual host node name>/<virtual host name>/<exchange name></para></listitem>
+ <listitem><para>/api/<version>/exchange/<virtual host node name>/<virtual host name>/<exchange name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) Exchanges(s) on Virtual Host and provides current values of Exchange attributes and its children</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/binding</para></listitem>
+ <listitem><para>/api/<version>/binding</para></listitem>
+ <listitem><para>/api/latest/binding/<virtual host node name></para></listitem>
+ <listitem><para>/api/<version>/binding/<virtual host node name></para></listitem>
+ <listitem><para>/api/latest/binding/<virtual host node name>/<virtual host name></para></listitem>
+ <listitem><para>/api/<version>/binding/<virtual host node name>/<virtual host name></para></listitem>
+ <listitem><para>/api/latest/binding/<virtual host node name>/<virtual host name>/<exchange name></para></listitem>
+ <listitem><para>/api/<version>/binding/<virtual host node name>/<virtual host name>/<exchange name></para></listitem>
+ <listitem><para>/api/latest/binding/<virtual host node name>/<virtual host name>/<exchange name>/<queue name>/<binding name></para></listitem>
+ <listitem><para>/api/<version>/binding/<virtual host node name>/<virtual host name>/<exchange name>/<queue name>/<binding name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes) Binding(s) of Queue to Exchange and provides current values of Binding attributes</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/connection</para></listitem>
+ <listitem><para>/api/<version>/connection</para></listitem>
+ <listitem><para>/api/latest/connection/<virtual host node name></para></listitem>
+ <listitem><para>/api/<version>/connection/<virtual host node name></para></listitem>
+ <listitem><para>/api/latest/connection/<virtual host node name>/<virtual host name></para></listitem>
+ <listitem><para>/api/<version>/connection/<virtual host node name>/<virtual host node name></para></listitem>
+ <listitem><para>/api/latest/connection/<virtual host node name>/<virtual host name>/<connection name></para></listitem>
+ <listitem><para>/api/<version>/connection/<virtual host node name>/<virtual host node name>/<connection name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages (deletes) Connection(s) on VirtualHost and provides current values of Connection attributes and its Sessions</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/session</para></listitem>
+ <listitem><para>/api/<version>/session</para></listitem>
+ <listitem><para>/api/latest/session/<virtual host node name></para></listitem>
+ <listitem><para>/api/<version>/session/<virtual host node name></para></listitem>
+ <listitem><para>/api/latest/session/<virtual host node name>/<virtual host name></para></listitem>
+ <listitem><para>/api/<version>/session/<virtual host node name>/<virtual host node name></para></listitem>
+ <listitem><para>/api/latest/session/<virtual host node name>/<virtual host name>/<connection name></para></listitem>
+ <listitem><para>/api/<version>/session/<virtual host node name>/<virtual host node name>/<connection name</para></listitem>
+ <listitem><para>/api/latest/session/<virtual host node name>/<virtual host name>/<connection name>/<session name></para></listitem>
+ <listitem><para>/api/<version>/session/<virtual host node name>/<virtual host node name>/<connection name>/<session name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages (deletes) Session(s) on Connection and provides values of Session attributes and its Consumers</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/port</para></listitem>
+ <listitem><para>/api/<version>/port</para></listitem>
+ <listitem><para>/api/latest/port/<port name></para></listitem>
+ <listitem><para>/api/<version>/port/<port name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) Port(s) on Broker and provides the information about current values of Port attributes and its children</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/authenticationprovider</para></listitem>
+ <listitem><para>/api/<version>/authenticationprovider</para></listitem>
+ <listitem><para>/api/latest/authenticationprovider/<authentication provider name></para></listitem>
+ <listitem><para>/api/<version>/authenticationprovider/<authentication provider name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) AuthenticationProvider(s) on Broker and provides the information about current values of AuthenticationProvider attributes and its children</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/user</para></listitem>
+ <listitem><para>/api/<version>/user</para></listitem>
+ <listitem><para>/api/latest/user/<authentication provider name>/<user name></para></listitem>
+ <listitem><para>/api/<version>/user/<authentication provider name>/<user name></para></listitem>
+ <listitem><para>/api/latest/user/<authentication provider name>/<user name></para></listitem>
+ <listitem><para>/api/<version>/user/<authentication provider name>/<user name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) User(s) on AuthenticationProvider and provides the information about current values of User attributes</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/accesscontrolprovider</para></listitem>
+ <listitem><para>/api/<version>/accesscontrolprovider</para></listitem>
+ <listitem><para>/api/latest/accesscontrolprovider/<access control provider name></para></listitem>
+ <listitem><para>/api/<version>/accesscontrolprovider/<access control provider name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) AccessControlProvider on Broker and provides the information about current values of AccessControlProvider attributes</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/groupprovider</para></listitem>
+ <listitem><para>/api/<version>/groupprovider</para></listitem>
+ <listitem><para>/api/latest/groupprovider/<group provider name></para></listitem>
+ <listitem><para>/api/<version>/groupprovider/<group provider name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) GroupProvider on Broker and provides the information about current values of GroupProvider attributes and its children</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/group</para></listitem>
+ <listitem><para>/api/<version>/group</para></listitem>
+ <listitem><para>/api/latest/group/<group provider name></para></listitem>
+ <listitem><para>/api/<version>/group/<group provider name></para></listitem>
+ <listitem><para>/api/latest/group/<group provider name>/<group name></para></listitem>
+ <listitem><para>/api/<version>/group/<group provider name>/<group name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) Group on GroupProvider and provides the information about current values of Group attributes and its children</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/groupmember</para></listitem>
+ <listitem><para>/api/<version>/groupmember</para></listitem>
+ <listitem><para>/api/latest/groupmember/<group provider name></para></listitem>
+ <listitem><para>/api/<version>/groupmember/<group provider name></para></listitem>
+ <listitem><para>/api/latest/groupmember/<group provider name>/<group name></para></listitem>
+ <listitem><para>/api/<version>/groupmember/<group provider name>/<group name></para></listitem>
+ <listitem><para>/api/latest/groupmember/<group provider name>/<group name>/<user name></para></listitem>
+ <listitem><para>/api/<version>/groupmember/<group provider name>/<group name>/<user name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes) GroupMember(s) on Group and provides the information about current values of GroupMember attributes</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/keystore</para></listitem>
+ <listitem><para>/api/<version>/keystore</para></listitem>
+ <listitem><para>/api/latest/keystore/<key store name></para></listitem>
+ <listitem><para>/api/<version>/keystore/<key store name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) KeyStore(s) on Broker and provides the information about current values of KeyStore attributes</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/truststore</para></listitem>
+ <listitem><para>/api/<version>/truststore</para></listitem>
+ <listitem><para>/api/latest/truststore/<trust store name></para></listitem>
+ <listitem><para>/api/<version>/truststore/<trust store name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) TrustStore(s) on Broker and provides the information about current values of TrustStore attributes</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/preferencesprovider</para></listitem>
+ <listitem><para>/api/<version>/preferencesprovider</para></listitem>
+ <listitem><para>/api/latest/preferencesprovider/<authentication provider name></para></listitem>
+ <listitem><para>/api/<version>/preferencesprovider/<authentication provider name></para></listitem>
+ <listitem><para>/api/latest/preferencesprovider/<authentication provider name>/<preferences provider name></para></listitem>
+ <listitem><para>/api/<version>/preferencesprovider/<authentication provider name>/<preferences provider name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) PreferencesProvider on AuthenticationProvider and provides the information about current values of PreferencesProvider attributes</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/plugin</para></listitem>
+ <listitem><para>/api/<version>/plugin</para></listitem>
+ <listitem><para>/api/latest/plugin/<plugin name></para></listitem>
+ <listitem><para>/api/<version>/plugin/<plugin name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) Plugin(s) on Broker and provides the information about current values of Plugin attributes</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <itemizedlist>
+ <listitem><para>/api/latest/replicationnode</para></listitem>
+ <listitem><para>/api/<version>/replicationnode</para></listitem>
+ <listitem><para>/api/latest/replicationnode/<virtual host node name></para></listitem>
+ <listitem><para>/api/<version>/replicationnode/<virtual host node name></para></listitem>
+ <listitem><para>/api/latest/replicationnode/<virtual host node name>/<replication node name></para></listitem>
+ <listitem><para>/api/<version>/replicationnode/<virtual host node name>/<replication node name></para></listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para>Manages(creates/deletes/updates) ReplicationNode(s) on VirtualHostNode and provides the information about current values of ReplicationNode attributes</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/message/<virtualhost name>/<queue name></para>
+ </entry>
+ <entry>Rest service to manage messages(s). Retrieves the details about the messages(s) with GET. Copies, moves messages with POST requests. Deletes messages with DELETE requests </entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/message-content/<virtualhost name>/<queue name></para>
+ </entry>
+ <entry>Rest service to retrieve message content</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/logrecords</para>
+ </entry>
+ <entry>Rest service to retrieve broker logs</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/sasl</para>
+ </entry>
+ <entry>Sasl authentication. Retrieves user current authentication status and broker supported SASL mechanisms (GET). Authenticates user using supported SASL mechanisms (PUT requests)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>/service/logout</para>
+ </entry>
+ <entry>Log outs user (GET only)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <section id="Java-Broker-Management-Channel-REST-API-Create">
+ <title>Configured Object creation</title>
+ <para>Methods PUT or POST can be used to create ConfiguredObject.</para>
+ <para>
+ 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.
+ </para>
+ <example>
+ <title>Examples of REST calls for Queue creation</title>
+ <para>
+ 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:
+ </para>
+ <screen><![CDATA[PUT /api/latest/queue/vhn/vh HTTP/1.1]]></screen>
+ <screen><![CDATA[POST /api/latest/queue/vhn/vh HTTP/1.1]]></screen>
+ <screen><![CDATA[PUT /api/latest/queue/vhn/vh/my-queue HTTP/1.1]]></screen>
+ <para>
+ 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.
+ </para>
+ </example>
+ </section>
+ <section id="Java-Broker-Management-Channel-REST-API-Update">
+ <title>Configured Object update</title>
+ <para>Methods PUT or POST can be used to update ConfiguredObject.</para>
+ <para>
+ 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.
+ </para>
+ <example>
+ <title>Examples of REST calls for Queue update</title>
+ <para>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:</para>
+ <screen><![CDATA[POST /api/latest/queue/vhn/vh/my-queue HTTP/1.1]]></screen>
+ <screen><![CDATA[POST /api/latest/queue/vhn/vh/my-queue HTTP/1.1]]></screen>
+ </example>
+ </section>
+ <section id="Java-Broker-Management-Channel-REST-API-Delete">
+ <title>Configured Object deletion</title>
+ <para>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.</para>
+ <para>On successful completion of operation a response code 200 should be returned.</para>
+ <para>With DELETE method object ConfiguredObject in following ways:</para>
+ <itemizedlist>
+ <listitem>
+ <para>by submitting DELETE request using ConfiguredObject full URI (the one ending with configured object name)</para>
+ </listitem>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </itemizedlist>
+ <example>
+ <title>Examples of REST calls for Queue deletion</title>
+ <para>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:</para>
+ <screen><![CDATA[DELETE /api/latest/queue/vhn/vh/my-queue HTTP/1.1]]></screen>
+ <screen><![CDATA[DELETE /api/latest/queue/vhn/vh?name=my-queue HTTP/1.1]]></screen>
+ <screen><![CDATA[DELETE /api/latest/queue/vhn/vh?id=real-queue-id HTTP/1.1]]></screen>
+ </example>
+ </section>
+ <section id="Java-Broker-Management-Channel-REST-API-Get">
+ <title>Retrieving Configured Object details</title>
+ <para>Method GET is used to retrieve ConfiguredObject attributes values and children hierarchy.</para>
+ <para>A particular ConfiguredObject details can be retrieved using full ConfiguredObject URI (the one ending with configured object name)</para>
+ <para>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.</para>
+ <para>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.</para>
+ <para>For example, for binding URL <literal>http://localhost:8080/api/latest/binding/<vhost
+ node>/<vhost>/<exchange>/<queue>/<binding></literal> replacing of
<literal><exchange></literal> with "asterisks"
(<literal>http://localhost:8080/api/<ver>/binding/<vhost
- node>/<vhost>/*/<queue>/<binding></literal>) 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.</para>
- <para>If <literal><binding></literal> and <literal><queue></literal> are omitted in
- binding REST URL (<literal>http://localhost:8080/api/<ver>/binding/<vhost
- node>/<vhost>/<exchangename></literal>) the GET request will result in
- returning all bindings for all queues for the given exchange in the virtual host. </para>
+ node>/<vhost>/*/<queue>/<binding></literal>) 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.</para>
+ <para>If <literal><binding></literal> and <literal><queue></literal> are omitted in
+ binding REST URL (<literal>http://localhost:8080/api/<ver>/binding/<vhost
+ node>/<vhost>/<exchangename></literal>) the GET request will result in
+ returning all bindings for all queues for the given exchange in the virtual host. </para>
+ <para>Additional parameters supported in GET requests:</para>
+ <variablelist>
+ <varlistentry>
+ <term>depth</term><listitem><para>To restrict the depth of hierarchy of configured objects to return in response</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>actuals</term><listitem><para>If set to "true" attribute actual values are returned instead of effective</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>includeSysContext</term><listitem><para>If set to "true" all system context variables are returned</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>inheritedActuals</term><listitem><para>If set to "true" actual values for all inherited context is returned.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>oversize</term><listitem><para>Sets the maximum length for values of over-sized attributes to trim</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>extractInitialConfig</term><listitem><para>If set to "true", the returned json can be used as initial configuration.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section id="Java-Broker-Management-Channel-REST-API-Examples">
+ <title>Examples of REST requests with curl</title>
<example>
<title>Examples of queue creation using curl (authenticating as user admin):</title>
<programlisting><![CDATA[
@@ -351,4 +516,5 @@ curl --user admin -X PUT -d '{}' http:/
necessary enable Basic authentication for HTTP within the HTTP Management Configuration (it is
off by default). For details see <xref linkend="Java-Broker-Management-Managing-Plugin-HTTP"/>
</para>
+ </section>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org