Usage Examples

Here are some examples using the HTTP API using available scripts.

Retrieving list of available ad-hoc commands

To retrieve a list of available commands, REST needs to use the GET method from the following resource: /rest/adhoc/sess-man@domain.com. This provides a list of available adhoc commands from the sess-man@domain.com resource. This can be change to any bare JID that you wish to get commands from so it can be a MUC room, monitor component, or in this case, the Session manager. With the server running, lets connect to the address http://localhost:8080/rest/ and the following resource /adhoc/sess-man@domain.com which will retrieve a list of all ad-hoc commands available at sess-man@domain.com. This particular action is protected by authentication using HTTP basic authentication so valid credentials are necessary. User credentials are available in the Tigase’s user database installation, so use the bare JID and password of an admin-authorized account to conduct this activity. The result will be an XML format output of available commands, similar to an IQ stanza, below an example of that result.

<items>
  <item>
    <jid>sess-man@domain.com</jid>
    <node>http://jabber.org/protocol/admin#get-active-users</node>
    <name>Get list of active users</name>
  </item>
  <item>
    <jid>sess-man@domain.com</jid>
    <node>del-script</node>
    <name>Remove command script</name>
  </item>
  <item>
    <jid>sess-man@domain.com</jid>
    <node>add-script</node>
    <name>New command script</name>
  </item>
</items>

There is also the ability to return a JSON formatted result. To achieve this, you need to pass Content-Type: application/json to the HTTP header of the request, or add the type parameter and set it to application/json setting. An example of a JSON result is below.

{
    "items": [
        {
            "jid": "sess-man@domain.com",
            "node": "http://jabber.org/protocol/admin#get-active-users",
            "name": "Get list of active users"
        },
        {
            "jid": "sess-man@domain.com",
            "node": "del-script",
            "name": "Remove command script"
        },
        {
            "jid": "sess-man@domain.com",
            "node": "add-script",
            "name": "New command script"
        }
    ]
}

Again, either of these methods can be used on any component with available ad-hoc commands. Feel free to experiment and see what options are available for each component.

Executing ad-hoc commands

Once you have found a command you wish to use, you can send that command using the HTTP POST method. In this example, lets request a list of active users as seen in the previous section. NOTE: like the previous example, these commands require basic HTTP authentication.

The following command is sent to http://localhost:8080/rest/adhoc/sess-man@domain.com

<command>
  <node>http://jabber.org/protocol/admin#get-active-users</node>
  <fields>
    <item>
      <var>domainjid</var>
      <value>domain.com</value>
    </item>
    <item>
      <var>max_items</var>
      <value>25</value>
    </item>
  </fields>
</command>

This particular command reqiures the three fields <node>, domainjid, and max_items. These three values are the node for the command, as returned in available commands, the domain results are to be returned from, and the maximum number of results. Keep in mind that Content-type: text/xml must be passed to the HTTP header to get an XML result. Not doing so may yield errors or incomprehensible results. The result for this command will look like this:

<command>
  <jid>sess-man@domain.com</jid>
  <node>http://jabber.org/protocol/admin#get-active-users</node>
  <fields>
    <item>
      <var>Users: 3</var>
      <label>text-multi</label>
      <value>admin@domain.com</value>
      <value>user1@domain.com</value>
      <value>morbo@domain.com</value>
    </item>
  </fields>
</command>

Similar results can be sent and received using JSON in a similar fashion. Again, be sure to set ContentType: application/json in the header or default settings.

{
  "command" : {
    "node" : "http://jabber.org/protocol/admin#get-active-users",
    "fields" : [
      {
        "var" : "domainjid",
        "value" : "subdomain.domain.com"
      },
      {
        "var" : "max_items",
        "value" : "25"
      }
    ]
  }
}

The results will look quite similar to the XML results:

{
    "command": {
        "jid": "sess-man@domain.com",
        "node": "http://jabber.org/protocol/admin#get-active-users",
        "fields": [
            {
                "var": "Users: 2",
                "label": "text-multi",
                "value": [
                  "minion1@subdomain.domain.com",
                  "overadmin@subdomain.domain.com"
                ]
            }
        ]
    }
}
Sending any XMPP Stanza

XMPP messages or any other XMPP stanza can be sent using this API by sending HTTP POST request on http://localhost:8080/rest/stream/api-key=API_KEY with a serialized XMPP stanza as content, where API_KEY is the API key specified in the init.properties file. Each request needs to be authorized by sending a valid administrator JID and password as a user/password of BASIC HTTP authorization method. The content of the HTTP request should be encoded in UTF-8 and Content-Type should be set to application/xml.

Handling of request

If no from attribute is set in the stanza, the HTTP API component will supplant it’s JID instead, however if one is set it will be preserved. However, in iq stanzas, if no from attribute is set the HTTP response content will be sent back as a response. Successful requests will return a HTTP response code of 200.

Examples: Any of these examples must be sent as an HTTP POST request to /rest/stream/?api-key=API_KEY of the HTTP API component.

Sending XMPP message with from set to HTTP API component a full JID
<message xmlns="jabber:client" type="chat" to="test@example.com/resource-1">
    <body>Example message 1</body>
</message>
Sending XMPP message with from set to HTTP API component with a bare JID
<message xmlns="jabber:client" type="chat" to="test@example.com">
    <body>Example message 1</body>
</message>
Sending XMPP message with from set to a specified JID to a full JID
<message xmlns="jabber:client" type="chat" from="sender@example.com" to="test@example.com/resource-1">
    <body>Example message 1</body>
</message>