REST API & PubSub

All PubSub Scripts are found within the scripts/rest/pubsub directory of Tigase’s installation directory. All examples in this section are prepared for a PubSub component available at pubsub@example.com. To use these examples for your installation, that JID needs to be replaced with with your pubsub JID.

All parameters passed in the content of HTTP request needs to be wrapped with <data/> tag at the root of the XML document. Returned results will be wrapped within the <result/> tag in the root of the XMl document.

Create a Node

HTTP URL: example.com/rest/pubsub/pubsub@example.com/create-node

Available HTTP methods:

GET

Method returns example content which contains all required and optional parameters that may be passed to the newly created node.

POST

Command requires fields node and pubsub#node_type to be filled with proper values for execution.

  • node Field contains id of node to create
  • owner Field may contain JID or JIDS which will be considered owner of the node. If this field is empty, server will use JID of HTTP API Component (rest@example.com)
  • pubsub#node_type Field should contain one of two types:

    • leaf Node to items that will be published
    • collection Node to nodes what will contain other nodes

Below is an example of creating a leaf type node with the owner set to admin@example.com.

<data>
  <node>example</node>
  <owner>admin@example.com</owner>
  <pubsub prefix="true">
    <node_type>leaf</node_type>
  </pubsub>
</data>

Server response:

<result>
  <Note type="fixed">
    <value>Operation successful</value>
  </Note>
</result>
Delete a node

HTTP URL: example.com/rest/pubsub/pubsub@example.com/delete-node

Available HTTP methods:

GET

Command returns example content which contains all required and operational parameters that may be passed.

POST

Command requires field node to be filled where node is the id of the node to delete.

Below is an example of removing a node with an id of example

<data>
  <node>example</node>
</data>

Server response

<result>
  <Note type="fixed">
    <value>Operation successful</value>
  </Note>
</result>
Subscribe to a node

HTTP URI: example.com/rest/pubsub/pubsub@example.com/subscribe-node

Available HTTP methods:

GET

Method returns example content which contains all required and optional parameters that may be passed.

POST

Command requires node and jid fields to be filled.

  • node is the id of the node to subscribe too.
  • jid is the JID or JIDS to be subscribed to the node.

Below is an example of the XML information passed between client and server with test1@example.com and test2@example.com subscribing to example node.

<data>
  <node>example</node>
  <jids>
    <value>test1@example.com</value>
    <value>test2@example.com</value>
  </jids>
</data>

Server response:

<result>
  <Note type="fixed">
    <value>Operation successful</value>
  </Note>
</result>
Unsubscribe from a node

HTTP URI: example.com/rest/pubsub/pubsub@example.com/unsubscribe-node

Available HTTP methods:

GET

Method returns example content which contains all required and optional parameters that may be passed.

POST

Like the Subscribe to a node section, the command requires both the node and jid fields to be filled.

  • node is the id of the node to unsubscribe from.
  • jid is the JID or JIDS to be unsubscribed from the node.

Below is an example of the XML information passed between client and server with test1@example.com and test2@example.com unsubscribing to example node.

<data>
  <node>example</node>
  <jids>
    <value>test@example.com</value>
    <value>test2@example.com</value>
  </jids>
</data>

Server response:

<result>
  <Note type="fixed">
    <value>Operation successful</value>
  </Note>
</result>
Publish an item to a node

HTTP URI: example.com/rest/pubsub/pubsub@example.com/publish-item

Available HTTP methods:

GET

Method returns example content which contains all required and optional parameters that may be passed.

POST

Command requires the node and entry fields to be filled. Available fields:

  • node Field contains the id of the node to be published to.
  • item-id Field to contain the id of the entry to publish.
  • expire-at Field may contain a timestamp after which item should not be delivered to subscribed users. Timestamp should follow this pattern: YYYY-MM-DDhh:mm:ss with a trailing Z to indicate UTC time in a 24h format.
  • entry Field should contain multi-line entry content which should be valid XML value for an item.

Below is an example exchange between client and server for publishing an item with id item-1 to node example .

<data>
  <node>example</node>
  <item-id>item-1</item-id>
  <expire-at>2015-05-13T16:05:00+02:00</expire-at>
  <entry>
    <item-entry>
      <title>Example 1</title>
      <content>Example content</content>
    </item-entry>
  </entry>
</data>

Server response:

<result>
  <Note type="fixed">
    <value>Operation successful</value>
  </Note>
</result>
List Available Nodes

HTTP URI: example.com/rest/pubsub/pubsub.example.com/list-nodes

Available HTTP methods

GET

This method returns list of available PubSub nodes for the domain passed as part of the URI (pubsub.example.com).

Below is an example exchange between client and server for listing all nodes, the result having test, node_54idf40037 and node_3ws5lz0037

<result>
<title>List of available nodes</title>
<nodes label="Nodes" type="text-multi">
<value>test</value>
<value>node_54idf40037</value>
<value>node_3ws5lz0037</value>
</nodes>
</result>
List Published Items on Node

HTTP URI: example.com/rest/pubsub/pubsub.example.com/list-items

Available HTTP methods

GET

Method returns example content which contains all required and optional parameters that may be passed.

POST

This command requires the node field to be filled. The node field contains the ID of the node from which we want the list of published items.

Below is an example exchange between client and server asking for all items published in the example node.

<data>
<node>example</node>
</data>

Server Response

<result>
<title>List of PubSub node items</title>
<node label="Node" type="text-single">
<value>example</value>
</node>
<items label="Items" type="text-multi">
<value>item-1</value>
<value>item-2</value>
</items>
</result>

Items item-1 and item-2 are the listed items.

Retrieve Published Item on Node

HTTP URI: example.com/rest/pubsub/pubsub.example.com/retrieve-item

Available HTTP methods

GET

Method returns example content which contains all required and optional parameters that may be passed.

POST

Command requires that fields node and item-id are filled. Available Fields: - node The node the item is published to. - item-id The id of the item you wish to retrieve.

Example communication between client and server:

<data>
<node>example</node>
<item-id>item-1</item>
</data>

Server response:

<result>
<title>Retrive PubSub node item</title>
<node label="Node" type="text-single">
<value>example</value>
</node>
<item-id label="Item ID" type="text-single">
<value>item-1</value>
</item-id>
<item label="Item" type="text-multi">
<value>&lt;item expire-at=&quot;2015-05-13T14:05:00Z&quot; id=&quot;item-1&quot;&gt;&lt;item-entry&gt;
&lt;title&gt;Example 1&lt;/title&gt;
&lt;content&gt;Example content&lt;/content&gt;
&lt;/item-entry&gt;&lt;/item&gt;
</value>
</item>
</result>

Node that inside the item element, there is an XML encoded element, this will be retrieved without any decoding.