Usage Examples

Usage Examples
Prev	Chapter 2. REST API	Next

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

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

Note

{
  "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).