PunJab - A Jabber XMLRPC/SOAP/REST client.
PunJab is a XMLRPC/SOAP/REST jabber client. It is a SOAP, XMLRPC, or REST server that allows persistent client connections to a jabber server. It can be used for many things, but its main purpose is to allow for stateless applications (ie web) a stateful connection to jabber.
News
Downloads
CVS
Docs
Bugs
Demo
XMLRPC API
REST API
About PunJab
SourceForge.net Logo
Chat Demo

Punjab REST API


This is the REST api to Punjab. The API is a set of global methods GET, POST, PUT, and DELETE and can be used regardless of differing operating systems and environments. This documentation describes the resources that punjab makes available via these global methods. Punjab provides a set of REST resources to make client connections to a jabber server.

Table of contents
login - connect and login to a jabber server.
logout - disconnect from the jabber server and close your session.
presences - retrieve and manipulate XMPP presence xml
messages - retrieve and manipulate XMPP message xml
iqs - retrieve and manipulate XMPP iq xml
vcard - retrieve and manipulate user vCard xml
browse - browse jabber entities
roster - retrieve and manipulate your jabber roster
help - a help resource for punjab
gmtime - return date time on punjab server
date - return date time on punjab server
ls - list all available resources

login -


connect and login to a jabber server.

Methods

GET - will send basic auth asking for username and password.
POST - will send basic auth asking for username and password.
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. [int] (defaults to 5222)
    • port - the jabber server port
Example Connect :
GET http://thetofu.com:32080/login?port=5223
Authorization: Basic KDENfKdifwekFD23nf==

Example Return Connect :
Content-Length: 88
Content-Type: text/xml
Client-Date: Mon, 10 May 2004 21:16:43 GMT
Client-Response-Num: 1

<?xml version="1.0"?>
<login>
  <sid>432sdfdsfsjgkghrtr;gfd'fd0108e8d48e9fdsdsfdsfdsewrerwe12a76</sid>
</login>

logout -


logout from the jabber server and close your session.

Methods

GET - disconnects you from the jabber server and destroys the session.
POST - disconnects you from the jabber server and destroys the session.
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. [string]
    • sid - the punjab session identifier
Example disconnect :
GET http://thetofu.com:32080/logout
Authorization: Basic fdsfsdgsdUB0aGV0bfdsfsdr4ew342rsfdfsd
Example Return disconnect :
Content-Length: 90
Content-Type: text/xml
Client-Date: Mon, 10 May 2004 21:31:38 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<logout><sid>1234dfghyujkoplacfd01023456yh9fe49e12a76</sid></logout>

presences -


retrieve and manipulate XMPP presence xml

Methods

GET - retrieve presence xml that has been sent to you
POST - send presence xml to punjab to be sent via jabber
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. [string]
    • sid - the punjab session identifier
  2. [string]
    • to - retrieve or manipulate only presence that has the 'to' attribute set to this value.
  3. [string]
    • from - retrieve or manipulate only presence that has the 'from' attribute set to this value.
Example GET :
GET http://thetofu.com:32082/presences?from=zorncj@jabber.musc.edu
Authorization: Basic 432dffdsfsdfdsgfdgfdgdfgferewrew765uhjdsdfMHJu

Example GET Return :
Content-Length: 254
Content-Type: text/xml
Client-Date: Tue, 11 May 2004 14:32:05 GMT
Client-Response-Num: 1
                                                                                                                                               
<?xml version="1.0"?>
<presences>
   <presence to='tofu@thetofu.com' from='zorncj@jabber.musc.edu/Psi'>
      <status>Online</status>
      <priority>5</priority>
      <x xmlns='jabber:x:delay' stamp='20040511T13:41:22' from='zorncj@jabber.musc.edu/Psi'/>
   </presence>
</presences>
Example POST :
POST http://thetofu.com:32082/presences
Authorization: Basic dasdasdsasadasdsadgfewqrqwewqpaMHJu
User-Agent: lwp-request/2.06
Content-Length: 102
Content-Type: application/x-www-form-urlencoded

<?xml version="1.0"?>
<presences>
   <presence>
       <status>Online</status>
       <priority>5</priority>
   </presence>
</presences>

Example POST Return (an error will be returned if not successful) :
Content-Length: 116
Content-Type: text/xml
Client-Date: Tue, 11 May 2004 14:28:26 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<presences>
   <presence>
       <status>Online</status>
       <priority>5</priority>
   </presence>
</presences>

messages -


retrieve and manipulate XMPP message xml

Methods

GET - retrieve message xml that has been sent to you
POST - send message xml to punjab to be sent via jabber
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. [string]
    • sid - the punjab session identifier
  2. [string]
    • to - the to attribute of the message packet you would like to retrieve
  3. [string]
    • type - the type attribute of the message packet you would like to retrieve (error,message,chat,etc)
  4. [string]
    • id - the id attribute or thread id of the message packet you would like to retrieve
  5. [string]
    • from - the from attribute of the message you would like to retrieve
  6. [string]
    • check - only check for messages, do not delete
Example GET :
GET http://thetofu.com:32082/messages?sid=fdsdfssdffsdrewr324trtsdfgytrwtwertewfs

Example GET Return :
Content-Length: 253
Content-Type: text/xml
Client-Date: Tue, 11 May 2004 14:46:32 GMT
Client-Response-Num: 1
                                                                                                                                               
<?xml version="1.0"?>
<messages>
   <message to='tofu@thetofu.com' from='zorncj@jabber.musc.edu/Psi' type='chat'>
      <body>yo</body>
   </message>
   <message to='tofu@thetofu.com' from='zorncj@jabber.musc.edu/Psi' type='chat'>
      <body>what up?</body>
   </message>
</messages>
Example POST :
POST http://thetofu.com:32082/messages?sid=fdsdfssdffsdrewr324trtsdfgytrwtwertewfs

<?xml version="1.0"?>
<messages>
  <message to='greggmc@jabber.musc.edu' type='chat'>
      <body>test</body>
  </message>
</messages>

Example POST Return (an error will be returned if not successful) :
Content-Length: 126
Content-Type: text/xml
Client-Date: Tue, 11 May 2004 14:51:21 GMT

<?xml version="1.0"?>
<messages>
  <message to='greggmc@jabber.musc.edu' type='chat'>
      <body>test</body>
  </message>
</messages>

iqs -


retrieve and manipulate XMPP iq xml

Methods

GET - retrieve iq xml that has been sent to you
POST - send iq xml to punjab to be sent via jabber
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. [string]
    • sid - the punjab session identifier
  2. [string]
    • id - the id attribute of the iq packet you would like to retrieve
Example POST :
POST http://thetofu.com:32082/iqs
Authorization: Basic dsafe234dsaadsasdaewwefsdffsddsfpaMHJu
Content-Length: 202
Content-Type: application/x-www-form-urlencoded

 
<?xml version="1.0"?>
<iqs>
  <iq to='ljud.jabber.musc.edu' type='set' id='abdda'>
    <query xmlns='jabber:iq:search'>
       <username>zorncj</username>
       <name/>
       <first/>
       <last/>
       <email/>
    </query>
  </iq>
</iqs>
Example POST Return (an error will be returned if not successful) :
Content-Length: 187
Content-Type: text/xml
Client-Date: Tue, 11 May 2004 20:02:43 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<iqs>
  <iq to='ljud.jabber.musc.edu' type='set' id='abdda'>
    <query xmlns='jabber:iq:search'>
       <username>zorncj</username>
       <name/>
       <first/>
       <last/>
       <email/>
    </query>
  </iq>
</iqs>

Example GET :
GET http://thetofu.com:32082/iqs
Authorization: Basic 1234ybmNqQdsffds90342YYHscfsfsdirew8943278kdS95bzfdsfsdfdsdfsQ12

Example GET Return :
Content-Length: 376
Content-Type: text/xml
Client-Date: Tue, 11 May 2004 20:16:20 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<iqs>
  <iq to='zorncj@jabber.musc.edu/yo' from='ljud.jabber.musc.edu' type='result' id='abdda'>
    <query xmlns='jabber:iq:search'>
      <item jid='zorncj@jabber.musc.edu'>
        <email>zorncj@musc.edu</email>
	<first>Christopher</first>
	<last>Zorn</last>
	<name>Christopher Zorn</name>
	<team>Information Technology Lab</team>
	<username>zorncj</username>
      </item>
    </query>
  </iq>
</iqs>

vcard -


retrieve and manipulate vCard xml

Methods

GET - retrieve vcard xml that has been sent to you
POST - send vcard xml to punjab to be sent via jabber
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. [string]
    • sid - the punjab session identifier
  2. [string]
    • jid - the jabber id of the vcard xml
Example GET :
GET http://thetofu.com:32082/vcard?jid=tofu@thetofu.com
Authorization: Basic oKIamnotap@55w0rd2Z1LdsadasS95bzpa123456
Example GET Return :
Content-Length: 185
Content-Type: text/xml
Client-Date: Tue, 11 May 2004 23:27:51 GMT
Client-Response-Num: 1

<?xml version="1.0"?>
<vCard prodid='-//HandGen//NONSGML vGen v1.0//EN' version='2.0'>
  <FN>TOfu</FN>
  <NICKNAME>tofu</NICKNAME>
  <URL>http://thetofu.com</URL>
  <ORG/>
  <ADR>
      <HOME/>
  </ADR>
</vCard>
Example POST :
POST http://thetofu.com:32082/vcard
Authorization: Basic 1234fdsjreJJTYSHR3423jfsoKJdsa2r
Content-Length: 163
Content-Type: application/x-www-form-urlencoded

<vCard prodid='-//HandGen//NONSGML vGen v1.0//EN' version='2.0'>
  <FN>Tofu</FN>
  <NICKNAME>tofu</NICKNAME>
  <URL>http://thetofu.com</URL>
  <ORG/>
  <ADR>
    <HOME/>
  </ADR>
</vCard>

Example POST Return (an error will be returned if not successful) :

Content-Length: 30
Content-Type: text/xml
Client-Date: Wed, 12 May 2004 00:15:53 GMT
Client-Response-Num: 1

<?xml version="1.0"?>
<vcard/>

browse -


browse jabber entities using jabber::iq::browse or disco

Methods

GET - browse jabber entities
POST - nothing
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. [string]
    • sid - the punjab session identifier
  2. [string]
    • jid - the jabber id of the entity you want to browse
Example GET :
GET http://thetofu.com:32082/browse?sid=9ZZZa6f75abhg5bCAfd110gE8d93e9fe49e12a56
Example GET Return :
Content-Length: 1322
Content-Type: text/xml
Client-Date: Wed, 12 May 2004 14:48:33 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<browse>
  <iq to='tofu@thetofu.com/yo' from='thetofu.com' id='P05vJDlY8IOUJ1F3d8C3' type='result'>
   <service xmlns='jabber:iq:browse' jid='thetofu.com' name='Jabber Server' type='jabber'>
      <service jid='jud.thetofu.com' name='ITLAB User Directory' type='jud'> 
        <ns>jabber:iq:search</ns>
	<ns>jabber:iq:register</ns>
      </service>
      <service jid='jmem.thetofu.com' name='Jmem testing' type='jmem'>
        <ns>jabber:iq:search</ns>
	<ns>jabber:iq:register</ns>
	<ns>jabber:iq:browse</ns>
      </service>
      <service jid='yahoo.thetofu.com' name='Yahoo! Transport' type='yahoo'>
           <ns>jabber:iq:gateway</ns>
	   <ns>jabber:iq:register</ns>
	   <ns>jabber:iq:version</ns>
	   <ns>jabber:iq:time</ns>
      </service>
      <service jid='aim.thetofu.com' name='AIM Transport' type='aim'>
           <ns>jabber:iq:gateway</ns>
	   <ns>jabber:iq:register</ns>
      </service>
      <service jid='rss.thetofu.com' name='RSS News Agent' type='rss'>
           <ns>jabber:iq:register</ns>
     </service>
     <conference jid='private.thetofu.com' name='Private Conferencing' type='private'/>
     <conference jid='conference.thetofu.com' name='Public Chatrooms' type='public'/>
   </service>
  </iq>
</browse>

roster -


manipulate or retrieve your jabber roster

Methods

GET - retrieve your jabber roster, presence tags are added if they exist
POST - manipulate your jabber roster
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. [string]
    • sid - the punjab session identifier
Example GET :
GET http://thetofu.com:32082/roster
Authorization: Basic dsafUUtopSaGV0b2Z1LmNvb1234568956aMHJZ

Example GET Return :
Content-Length: 1056
Content-Type: text/xml
Client-Date: Wed, 12 May 2004 16:09:44 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<roster>
  <item jid='tofu@thetofu.com' name='Tofu' subscription='both'>
    <group>Punjab</group>
    <presence to='anon@thetofu.com' from='tofu@thetofu.com/Psi'>
       <status>Online</status>
       <priority>5</priority>
       <x xmlns='jabber:x:delay' stamp='20040512T15:44:43' from='tofu@thetofu.com/Psi'/>
       <x xmlns='jabber:x:delay' stamp='20040512T15:49:23' from='tofu@thetofu.com/Psi'/>
    </presence>
  </item>
  <item jid='random@elitesecurity.org' subscription='none'/>
  <item jid='daneel@sourcecode.de' subscription='both'/>
  <item jid='jiffa@jabber.ru' subscription='none'/>
  <item jid='bhavin@vip3.vipn.net' name='Bhavin' ask='subscribe' subscription='none'/>
</roster>
Example POST :
POST http://thetofu.com:32082/roster
Authorization: Basic YW5vbkB0aGV0b2Z1LmNvbS95bzphbm9u
Content-Length: 99
Content-Type: application/x-www-form-urlencoded

<roster>
<item name="Templar" jid="bulsonm@jabber.musc.edu" >
<group>MUSC</group>
</item>
</roster>

Example GET POST :
Content-Length: 135
Content-Type: text/xml
Client-Date: Wed, 12 May 2004 17:20:20 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<roster>
  <iq to='anon@thetofu.com/yo' from='anon@thetofu.com/yo' id='cgPy6uDRABXv71R5PZ8' type='result'/>
</roster>

help -


A help system for punjab, similar to man.

Methods

GET - browse the help system
POST - nothing
PUT - nothing
DELETE - nothing

Arguments

  1. /help/<resource>/ - The resource is what you want help with.

Parameters

  1. none
Example GET :
GET http://thetofu.com:32082/help/messages
Example GET Return :
Content-Length: 327
Content-Type: text/xml
Client-Date: Wed, 12 May 2004 17:51:56 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<help id='messages'>
  <name>messages - a tool to send and recieve messages via a jabber server. </name>
  <synopsis> finish me </synopsis>
  <description>Messages is used to send and recieve messages using a jabber server. </description>
   <examples>       http://localhost/messages   </examples>
</help>

gmtime -


Display gmtime from the punjab server

Methods

GET - grab the gmtime on the punjab server
POST - nothing
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. none
Example GET :
GET http://thetofu.com:32082/gmtime
Example GET Return :
Content-Length: 86
Content-Type: text/xml
Client-Date: Wed, 12 May 2004 17:55:22 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<resources><gmtime>Wed May 12 17:58:49 2004</gmtime></resources>

date -


returns the current date on the punjab server.

Methods

GET - grab the current date on the punjab server
POST - nothing
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. none
Example GET :
GET http://thetofu.com:32082/date
Example GET Return :
Content-Length: 82
Content-Type: text/xml
Client-Date: Wed, 12 May 2004 17:56:42 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<resources><date>Wed May 12 14:00:09 2004</date></resources>

ls -


list punjab resources (not complete)

Methods

GET - list the resources available through punjab
POST - nothing
PUT - nothing
DELETE - nothing

Arguments

  1. none

Parameters

  1. none
Example GET :
GET http://thetofu.com:32082/ls
Example GET Return :
Content-Length: 618
Content-Type: text/xml
Client-Date: Wed, 12 May 2004 17:57:39 GMT
Client-Response-Num: 1
 
<?xml version="1.0"?>
<resources>
  <resource href='/ls/browse'>browse</resource>
  <resource href='/ls/messages'>messages</resource>
  <resource href='/ls/date'>date</resource>
  <resource href='/ls/gmtime'>gmtime</resource>
  <resource href='/ls/ls'>ls</resource>
  <resource href='/ls/login'>login</resource>
  <resource href='/ls/register'>register</resource>
  <resource href='/ls/iqs'>iqs</resource>
  <resource href='/ls/vcard'>vcard</resource>
  <resource href='/ls/presences'>presences</resource>
  <resource href='/ls/roster'>roster</resource>
  <resource href='/ls/help'>help</resource>
  <resource href='/ls/logout'>logout</resource>
</resources>