Data-API

 

Data-API

 

Methods

 

Hyves chat platform

Hyves Chat is implemented using the XMPP (formerly known as Jabber) standard.

The XMPP standard is extensively documented here:

http://www.xmpp.org/

XMPP allows for extensions in a clean way by using XML namespaces. Every XMPP client is supposed to ignore any XML elements that are in some namespace it does not support or recognize.

All Hyves specific extensions are in the namespace http://hyves.net/xmpp

Hyves Chat is open to all XMPP clients and should work with all of them. If you have problems using your own favorite client, please let us know, so that we can possibly fix our servers.

Hyves Chat supports authentication trough DIGEST-MD5 and old-style Jabber method. Currently The Hyves Client (Hyves Desktop) uses old-style Jabber login.

The Hyves API contains a method chat.getLoginToken that provides login tokens (digest) that can be used to log in to the chat system. The chat.getLoginToken returns both a login digest and an available chatserver to which you can connect your client.

If you create your own XMPP client, please use the same resource name for each client (for instance the Hyves Kwekker uses 'desktopClient'. Please do not use any of the following resources [desktopClient, webClient, siteClient]. A Hyves user can only be logged in to the chat once for each resource. If a client is started with the same resource as an already running client, the older running client will be logged of from the chat and the new one will be connected instead.

An example Hyves Chat login sequence

The following is an actual example of the Hyves Kwekker login in to the chat system for user 'toymachine'. The precise flow and meaning of the elements can be found in the XMPP protocol documentation.

client start stream:
 
<?xml version="1.0"?>
<flash:stream to="198.2.0.54" xmlns="jabber:client" xmlns:flash="http://www.jabber.com/streams/flash" version="1.0">
 
 
server responds and announces available authentication methods:
 
<?xml version='1.0' encoding='UTF-8'?>
        <stream:stream xmlns:stream="http://www.jabber.com/streams/flash" xmlns="jabber:client" id="1028" xml:lang="en" version="1.0"  from="hyves.nl">
        <stream:features>
              <mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
                <mechanism>DIGEST-MD5</mechanism>
              </mechanisms>
              <auth xmlns='http://jabber.org/features/iq-auth'/>
        </stream:features>
 
clients asks to authenticate user 'toymachine' using jabber authentication method (as opposed to digest-md5):
 
<iq id="log_user_1" type="get">
    <query xmlns="jabber:iq:auth"><username>toymachine</username></query>
</iq>
 
server asks for digest (token that can be retrieved with API call chat.getLoginToken) and resource:
 
        <iq type='result' id='log_user_1'>
          <query xmlns='jabber:iq:auth'>
            <username/>
            <digest/>
            <resource/>
          </query>
        </iq>
 
 
client provides token (from chat.getLoginToken API) and resource:
 
<iq id="log_user2_3" type="set">
<query xmlns="jabber:iq:auth">
<digest>dG95xWFjxGluZVxxMjE0ODk5N444XzWb3TMvsIVdYtrgRgVa6Xk=</digest>
<username>toymachine</username>
<resource>sampleClient</resource></query>
</iq>
 
server acknowledges correct login:
<iq type='result' id='log_user2_3'/>
 
client asks for roster (friends list):
 
<iq id="roster_5" type="get"><query xmlns="jabber:iq:roster" />
 
 
server responds with roster list:
 
<iq to='toymachine@hyves.nl/desktopClient' type='result' id='roster_5'><query xmlns='jabber:iq:roster'>
<item jid='koenkam@hyves.nl' name="Koen test jmeter" subscription='both'><group>Friends</group></item>
<item jid='raymond@hyves.nl' name="Raymond" subscription='both'><group>Friends</group></item>
...
...
</query></iq>
 
client asks for extended hyves roster (containing www's, media Ids etc):
 
<iq type='get' id='Hyves_Roster_Extension'><query xmlns='http://hyves.net/xmpp'/></iq>
 
server responds with 
 
1) the extended roster list (using hyves namspace http://hyves.net/xmpp)
 
<iq to='toymachine@hyves.nl/desktopClient' type='result' id='Hyves_Roster_Extension'><query xmlns='http://hyves.net/xmpp'>
<item jid="koenkam@hyves.nl" memberId="1" mediaId="2" mediaSecret="1a1b" whatsOnYourMind="" wwwEmotion="test www post locatie" wwwLocation="" wwwTime="20071127121905" blocked="False"/>
<item jid="raymond@hyves.nl" memberId="14" mediaId="15459411" mediaSecret="J2Nd" whatsOnYourMind="" wwwEmotion="kwkkn" wwwLocation="jimmhy" wwwTime="20080326182646" blocked="False"/>
...
...
</query></iq>.             
 
2) server provides some extra info on the logged in member:
        <iq to='toymachine@hyves.nl/desktopClient' type='set' id='1'><query xmlns='http://hyves.net/xmpp'>
            <item jid="toymachine@hyves.nl" memberId="1956" mediaId="14448013" mediaSecret="hKFw" whatsOnYourMind="" wwwEmotion="hjkhkjhadsfadf" wwwLocation="jlkjk" wwwTime="20080617104820" blocked="False"/>        
        </query></iq>
 
        <iq to='toymachine@hyves.nl/desktopClient' type='set' id='1'><query xmlns='http://hyves.net/xmpp'><item jid='toymachine@hyves.nl' nick="Henk" visibility='4' chatability='4'/></query></iq>.       
 
 
3) client annouces that it is present (notifications will be send to friends that x comes online)
 
  <presence><show>dnd</show><status>phone</status><priority>8</priority></presence>