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.
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>
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" } ] }
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)
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 &apos;vhost-tls-required&apos; property to &apos;false&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>
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 'vhost-tls-required' property to 'false' in the installation configuration file" }, { "var": "Max users", "value": "0" } … ], "instructions": "❗NOTE: Options without value set will use configuration defined in 'DEFAULT' VHost❗" } }
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
.
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>
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" ] } ] } }
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.
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>
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" : [] } }
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 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”.
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):
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>
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):
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." } ] } }
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”.
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):
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>
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):
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" : [] } }
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
.
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.
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>
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.You may add /{resource}
to the URL after /status
part, where {resource}
is name of the resource for which you want to set presence.
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.
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/disconnectedpriority
- 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).
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/disconnectedpriority
- 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).