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
|
- none
|
Parameters
|
- [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
|
- none
|
Parameters
|
- [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
|
- none
|
Parameters
|
- [string]
- sid - the punjab session identifier
- [string]
- to - retrieve or manipulate only presence that has the 'to' attribute set to this value.
- [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
|
- none
|
Parameters
|
- [string]
- sid - the punjab session identifier
- [string]
- to - the to attribute of the message packet you would like to retrieve
- [string]
- type - the type attribute of the message packet you would like to retrieve (error,message,chat,etc)
- [string]
- id - the id attribute or thread id of the message packet you would like to retrieve
- [string]
- from - the from attribute of the message you would like to retrieve
- [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
|
- none
|
Parameters
|
- [string]
- sid - the punjab session identifier
- [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
|
- none
|
Parameters
|
- [string]
- sid - the punjab session identifier
- [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
|
- none
|
Parameters
|
- [string]
- sid - the punjab session identifier
- [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
|
- none
|
Parameters
|
- [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
|
- /help/<resource>/ - The resource is what you want help with.
|
Parameters
|
- 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
|
- none
|
Parameters
|
- 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
|
- none
|
Parameters
|
- 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
|
- none
|
Parameters
|
- 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>
|
|