Usage Examples
Prev | Chapter 2. REST API | Next

## Usage Examples

### Retrieving user avatar

Request using GET method for url /rest/avatar/admin@test-domain.com will return an avatar image for user admin@test-domain.com if an avatar is set in user vCard or will otherwise return a http error 404. Example of full url for avatar of user admin@domain.com

    http://localhost:8080/rest/avatar/admin@domain.com

Entering this url in will execute GET request. It may be possible to use the url in your browser.

### Retrieving list of available adhoc commands

#### Using XML format

To retrieve a list of available adhoc commands, make a request using GET method for `/rest/adhoc/sess-man@domain.com` where `sess-man@domain.com` is jid of component you wish to see commands for. For example, entering the following url: http://localhost:8080/rest/adhoc/sess-man@domain.com in your browser will retrieve a list of all ad-hoc commands available at `sess-man@domain.com`. This action is protected by authentication done using `HTTP Basic Authentication`. Valid credentials will be those of users available in user database of this Tigase XMPP Server installation (username in barejid form).

Below is example result of that request:

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

#### Using JSON format

To retrieve a list of available adhoc commands in JSON, we need to pass `Content-Type: application/json` to HTTP header of request or add `type` parameter set to `application/json`. Example result 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"
            }
        ]
    }

### Retrieving command form

In order to retrieve form with required fields for particular command, you have to sent `POST` request with only `jid` and `name` from the list with all available commands (returned using above command)

#### Using XML

For example, to get form for adding VHost item make a request using `POST` method for `/rest/adhoc/vhost-man@domain.com` sending the following content (request requires authentication using Basic HTTP Authentication):

    <command>
        <node>comp-repo-item-add</node>
    </command>

Below is example result for request presented above:

    <command>
        <jid>vhost-man@domain.com</jid>
        <node>comp-repo-item-add</node>
        <fields>
            <item>
                <var>Domain name</var>
                <value/>
            </item>
            <item>
                <var>Enabled</var>
                <type>boolean</type>
                <value>true</value>
            </item>
            <item>
                <var>Anonymous enabled</var>
                <type>boolean</type>
                <value>true</value>
            </item>
            <item>
                <var>In-band registration</var>
                <type>boolean</type>
                <value>true</value>
            </item>
            <item>
                <var>TLS</var>
                <type>fixed</type>
                <value>This installation forces VHost to require TLS. If you need to use unencrypted connections set &amp;apos;vhost-tls-required&amp;apos;
                    property to &amp;apos;false&amp;apos; in the installation configuration file
                </value>
            </item>
            <item>
                <var>Max users</var>
                <value>0</value>
            </item>
            …
        </fields>
        <instructions>â—NOTE: Options without value set will use configuration defined in 'DEFAULT' VHostâ—</instructions>
    </command>

#### Using JSON

For example, to get form for adding VHost item make a request using `POST` method for `/rest/adhoc/vhost-man@domain.com` using `Content-Type: application/json` and sending the following content (request requires authentication using Basic HTTP Authentication) :

    {
      "command": {
        "node" : "comp-repo-item-add"
      }
    }

Below is an example result for request presented above:

    {
      "command": {
        "jid": "vhost-man@domain.com",
        "node": "comp-repo-item-add",
        "fields": [
          {
            "var": "Domain name",
            "value": null
          },
          {
            "var": "Enabled",
            "type": "boolean",
            "value": "true"
          },
          {
            "var": "Anonymous enabled",
            "type": "boolean",
            "value": "true"
          },
          {
            "var": "In-band registration",
            "type": "boolean",
            "value": "true"
          },
          {
            "var": "TLS",
            "type": "fixed",
            "value": "This installation forces VHost to require TLS. If you need to use unencrypted connections set &apos;vhost-tls-required&apos; property to &apos;false&apos; in the installation configuration file"
          },
          {
            "var": "Max users",
            "value": "0"
          }
          …
        ],
        "instructions": "❗NOTE: Options without value set will use configuration defined in 'DEFAULT' VHost❗"
      }
    }

### Executing example ad-hoc commands

#### Retrieving list of active users

##### Using XML

To execute the command to get a list of active users, make a request using POST method for `/rest/adhoc/sess-man@domain.com` sending the following content (request requires authentication using Basic HTTP Authentication):

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

In this request we passed all the parameters needed to execute adhoc command. We passed the node of the adhoc command and values for fields required by that command. We passed values of "domain.com" for "domainjid" field and "25" for "max_items" field. We also need to pass `Content-Type: text/xml` to HTTP header of request or add `type` parameter set to `text/xml`.

### Note

In case of multi value fields use following format:

    <value>
        <item>first-value</item>
        <item>second-value</item>
    </value>

Below is example result for request presented above:

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

##### Using JSON

To execute the command to get active users in JSON format, make a request using POST method for /rest/adhoc/sess-man@domain.com sending the following content (this request also requires authentication using Basic HTTP Authentication):

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

In this request we passed all parameters needed to execute adhoc command. We passed the node of adhoc command and values for fields required by adhoc command. In this case we passed value of "domain.com" for "domainjid" field and "25" for "max_items" field.

Below is an example result for request presented above:

    {
        "command": {
            "jid": "sess-man@domain.com",
            "node": "http://jabber.org/protocol/admin#get-active-users",
            "fields": [
                {
                    "var": "Users: 1",
                    "label": "text-multi",
                    "value": [
                      "admin@domain.com",
                      "user1@domain.com"
                    ]
                }
            ]
        }
    }

#### Ending a user session

To execute the end user session command, make a request using POST method for `/rest/adhoc/sess-man@domain.com`. The Context of what is sent, may differ depending on circumstance. For example, it may require authentication using Basic HTTP Authentication with admin credentials. sess-man@domain.com in URL is the JID of session manager component which usually is in form of sess-man@domain where `domain` is hosted domain name.

##### Using XML

To execute the command using XML content you need to set HTTP header `Content-Type` to `application/xml`

    <command>
      <node>http://jabber.org/protocol/admin#end-user-session</node>
      <fields>
        <item>
          <var>accountjids</var>
          <value>
            <item>test@domain.com</item>
          </value>
        </item>
      </fields>
    </command>

Where `test@domain.com` is JID of user which should be disconnected.

As a result server will return following XML:

    <command>
      <jid>sess-man@domain.com</jid>
      <node>http://jabber.org/protocol/admin#end-user-session</node>
      <fields>
        <item>
          <var>Notes</var>
          <type>text-multi</type>
          <value>Operation successful for user test@domain.com/resource</value>
         </item>
      </fields>
    </command>

This will confirm that user `test@domain.com` with resource `resource` was connected and has been disconnected.

If the user was not connected server will return following response:

    <command>
      <jid>sess-man@domain.com</jid>
      <node>http://jabber.org/protocol/admin#end-user-session</node>
      <fields />
    </command>

##### Using JSON

To execute the command using JSON you will need to set HTTP header `Content-Type` to `application/json`

    {
      "command" : {
      	"node": "http://jabber.org/protocol/admin#end-user-session",
      	"fields": [
    		{
    	    	"var" : "accountjids",
    			"value" : [
    				"test@domain.com"
    			]
    		}
      	]
      }
    }

Where `test@domain.com` is JID of user who will be disconnected

As a result, the server will return following JSON:

    {
      "command" : {
        "jid" : "sess-man@domain.com",
        "node" : "http://jabber.org/protocol/admin#end-user-session",
        "fields" : [
          {
            "var" : "Notes",
            "type" : "text-multi",
            "value" : [
              "Operation successful for user test@domain.com/resource"
            ]
          }
       ]
      }
    }

To confirm that user `test@domain.com` with resource `resource` was connect and it was disconnected.

If user was not connected server will return the following response:

    {
      "command" : {
        "jid" : "sess-man@domain.com",
        "node" : "http://jabber.org/protocol/admin#end-user-session",
        "fields" : []
      }
    }

### Operations on VHosts/Domains

All operations on VHosts are done by making a `POST` request to `/rest/adhoc/vhost-man@domain.com` (it may require authentication using Basic HTTP Authentication with admin credentials). When deciding to use XML or JSON set relevant `Content-Type` header.

#### Adding VHost

Adding domain is done using `comp-repo-item-add` command sent with all required and desired fields (if something is missing form-to-fill-out will be returned). For the instructions how to retrieve the form/available fields please see the section called “Retrieving command form”.

##### Using XML

To execute the command using XML content you need to set HTTP header `Content-Type` to `application/xml` and the filled out form (below is trimmed example, see the section called “Retrieving command form” for details how to get complete form):

### Note

It’s essential to include `command-marker` in the request, otherwise the form will be returned without adding the VHost.

    <command>
        <jid>vhost-man@domain.com</jid>
        <node>comp-repo-item-add</node>
        <fields>
            <item>
                <var>Domain name</var>
                <value>my-new-domain.com</value>
            </item>
            <item>
                <var>Enabled</var>
                <value>true</value>
            </item>
            <item>
                <var>command-marker</var>
                <value>command-marker</value>
            </item>
            …
        </fields>
    </command>

If the domain was added correctly you will receive response with `Operation successful.` Note field:

    <command>
        <jid>vhost-man@domain.com</jid>
        <node>comp-repo-item-add</node>
        <fields>
            <item>
                <var>Note</var>
                <type>fixed</type>
                <value>Operation successful.</value>
            </item>
        </fields>
    </command>

##### Using JSON

To execute the command using XML content you need to set HTTP header `Content-Type` to `application/json` and the filled out form (below is trimmed example, see the section called “Retrieving command form” for details how to get complete form):

### Note

It’s essential to include `command-marker` in the request, otherwise the form will be returned without adding the VHost.

    {
      "command": {
        "jid": "vhost-man@domain.com",
        "node": "comp-repo-item-add",
        "fields": [
          {
            "var": "Domain name",
            "value": "my-new-awesome-domain.com"
          },
          {
            "var": "Enabled",
            "value": "true"
          },
          {
            "var": "command-marker",
            "value": "command-marker"
          }
          …
        ]
      }
    }

If the domain was added correctly you will receive response with `Operation successful.` Note field:

    {
      "command": {
        "jid": "vhost-man@domain.com",
        "node": "comp-repo-item-add",
        "fields": [
          {
            "var": "Note",
            "type": "fixed",
            "value": "Operation successful."
          }
        ]
      }
    }

#### Configuring VHost

Modifying domain configuration is done using `comp-repo-item-update` command sent with all required and desired fields (if something is missing form-to-fill-out will be returned). For the instructions how to retrieve the form/available fields please see the section called “Retrieving command form”.

##### Using XML

To execute the command using XML content you need to set HTTP header `Content-Type` to `application/xml` and the filled out form (below is trimmed example, see the section called “Retrieving command form” for details how to get complete form):

### Note

It’s essential to include `command-marker` in the request (otherwise the form will be returned without adding the VHost) and `item-list` with value set to the name of the VHost that’s being configured.

    <command>
        <jid>vhost-man@domain.com</jid>
        <node>comp-repo-item-update</node>
        <fields>
            <item>
                <var>Domain name</var>
                <value>my-vhost.com</value>
            </item>
            <item>
                <var>Enabled</var>
                <value>true</value>
            </item>
            …
            <item>
                <var>command-marker</var>
                <value>command-marker</value>
            </item>
            <item>
                <var>item-list</var>
                <value>my-vhost.com</value>
            </item>
        </fields>
    </command>

If the domain was added correctly you will receive response with `Operation successful.` Note field:

    <command>
        <jid>vhost-man@domain.com</jid>
        <node>comp-repo-item-update</node>
        <fields>
            <item>
                <var>Note</var>
                <type>fixed</type>
                <value>Operation successful.</value>
            </item>
        </fields>
    </command>

##### Using JSON

To execute the command using XML content you need to set HTTP header `Content-Type` to `application/json` and the filled out form (below is trimmed example, see the section called “Retrieving command form” for details how to get complete form):

### Note

It’s essential to include `command-marker` in the request (otherwise the form will be returned without adding the VHost) and `item-list` with value set to the name of the VHost that’s being configured.

    {
      "command": {
        "jid": "vhost-man@domain.com",
        "node": "comp-repo-item-update",
        "fields": [
          {
            "var": "Domain name",
            "value": "my-domain.com"
          },
          {
            "var": "Enabled",
            "value": "true"
          },
          …
          {
            "var": "command-marker",
            "value": "command-marker"
          },
          {
            "var": "item-list",
            "value": "my-domain.com"
          }
        ]
      }
    }

If the domain was added correctly you will receive response with `Operation successful.` Note field:

    {
      "command": {
        "jid": "vhost-man@domain.com",
        "node": "comp-repo-item-update",
        "fields": [
          {
            "var": "Note",
            "type": "fixed",
            "value": "Operation successful."
          }
        ]
      }
    }

To confirm that user `test@domain.com` with resource `resource` was connect and it was disconnected.

If user was not connected server will return the following response:

    {
      "command" : {
        "jid" : "sess-man@domain.com",
        "node" : "http://jabber.org/protocol/admin#end-user-session",
        "fields" : []
      }
    }

### Sending any XMPP Stanza

XMPP messages or any other XMPP stanza can be sent using this API by sending an HTTP POST request to (by default) `http://localhost:8080/rest/stream/?api-key=API_KEY` with serialized XMPP stanza as a content, where `API_KEY` is the API key for HTTP API. This key is set in etc/config.tdsl. Also, each request needs to be authorized by sending a valid administrator JID and password as user and password of BASIC HTTP authorization method. Content of HTTP request should be encoded in `UTF-8` and `Content-Type` should be set to `application/xml`.

#### Handling of request

If the sent XMPP stanza does not contain a `from` attribute, then the HTTP API component will provide it’s own JID. If `iq` stanza is being sent, and no `from` attribute is set then the received response will be returned as the content of the HTTP response. Successful requests will return HTTP response code 200.

#### Examples

Sending an XMPP message with from set to HTTP API component to full JID. Data needs to be sent as a HTTP POST request content to `/rest/stream/?api-key=API_KEY` URL of the HTTP API component to deliver the message Example message 1 to test@example.com/resource-1.

    <message xmlns="jabber:client" type="chat" to="test@example.com/resource-1">
        <body>Example message 1</body>
    </message>

Sending an XMPP message with `from` set to HTTP API component to a bare JID. Data needs to be sent as a HTTP POST request content to `/rest/stream/?api-key=API_KEY` URL of the HTTP API component to deliver message Example message 2 to test@example.com.

    <message xmlns="jabber:client" type="chat" to="test@example.com">
        <body>Example message 2</body>
    </message>

Sending an XMPP message with `from` set to specified JID and to a recipients' full JID. Data needs to be sent as a HTTP POST request content to `/rest/stream/?api-key=API_KEY` URL of the HTTP API component to deliver message Example message 3 to test@example.com/resource-1 with sender of message set to sender@example.com.

    <message xmlns="jabber:client" type="chat" from="sender@example.com" to="test@example.com/resource-1">
        <body>Example message 1</body>
    </message>

### Setting XMPP user status

By default XMPP user is visible as unavailable when his client is disconnected. However in some cases we may want to present user a active with some particular presence being set. To control this presence of unavailable XMPP user we can use this feature.

Example contents shown below needs to be sent to (by default) `http://localhost:8080/rest/user/{user-jid}/status?api-key=API_KEY`, where:

- `API_KEY` is the API key for HTTP API
- `{user-jid}` is a bare jid of the user for which you want to set presence.

### Tip

You may add `/{resource}` to the URL after `/status` part, where `{resource}` is name of the resource for which you want to set presence.

### Warning

You need to add `'user-status-endpoint@http.{clusterNode}'` to the list of trusted jids to allow UserStatusEndpoint module to properly integrate with Tigase XMPP Server.

#### Using XML

To set user status you need to set HTTP header `Content-Type` to `application/xml`

    <command>
        <available>true</available>
        <priority>-1</priority>
        <show>xa</show>
        <status>On the phone</status>
    </command>

where:

- `available` - may be:

  - `true` - user is available/connected (default)
  - `false` - user is unavailable/disconnected
- `priority` - an integer of presence priority. (It should be always set as a negative value to make sure that messages are not dropped) (default: -1)

- `show` - may be one of `presence/show` element values (optional)

  - `chat`
  - `away`
  - `xa`
  - `dnd`
- `status` - message which should be sent as a presence status message (optional)

As a result server will return following XML:

    <status>
      <user>test@domain.com/tigase-external</user>
      <available>true</available>
      <priority>priority</priority>
      <show>xa</show>
      <status>On the phone</status>
      <success>true</success>
    </status>

This will confirm that user `test@domain.com` with resource `tigase-external` has it presence changed (look for `success` element value).

#### Using JSON

To set user status you need to set HTTP header `Content-Type` to `application/json`

    {
      "available": "true",
      "priority": "-1",
      "show": "xa",
      "status": "On the phone"
    }

where:

- `available` - may be:

  - `true` - user is available/connected (default)
  - `false` - user is unavailable/disconnected
- `priority` - an integer of presence priority. (It should be always set as a negative value to make sure that messages are not dropped) (default: -1)

- `show` - may be one of `presence/show` element values (optional)

  - `chat`
  - `away`
  - `xa`
  - `dnd`
- `status` - message which should be sent as a presence status message (optional)

As a result, the server will return following JSON:

    {
      "status": {
        "user": "test@domain.com/tigase-external",
        "available": "true",
        "priority": "-1",
        "show": "xa",
        "status": "On the phone",
        "success": true
      }
    }

This will confirm that user `test@domain.com` with resource `tigase-external` has it presence changed (look for `success` element value).

Prev | Up | Next
Chapter 2. REST API | Home | BOSH HTTP Pre-Binding