Xmpp Client API (draft)

Overview

Client Discovery

Any client that speaks the Xmpp protocol can be a Notify.me api client. All that is required for our servers to treat it as such is that the client identifies itself appropriately during discovery time.

When a client sends presence to a Notify.me agent (currently there exist only athena@agents.notify.me and zeus@agents.notify.me, check your IM to see who you are subscribed to), the agent will send back the standard service discovery stanza:

<iq type='get'
    from='(athena|zeus)@agents.notify.me/agent'
    to='foo@bar.com'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

As part of the usualy capabilities, such as Xhtml-IM, an api client needs to announce that they support the Notify.me client-api, which is identified by the http://notify.me/protocol/client-api namespace such as:

<iq type='result'
    from='foo@bar.com/baz'
    to='(athena|zeus)@agents.notify.me/agent'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='http://notify.me/protocol/client-api'/>
    ...
  </query>
</iq>

Once the agent has recognized the client as an api client, it can be addressed with api commands (coming in the future) and will be sent api formatted messages, rather than IM client formatted messages. More infomation about the discovery protocol can be found in XEP-0030.

Api Formatted Messages

Notifications are sent clustered as a single message stanza. Instead of the usual subject element, an API message will contain a data element in the http://notify.me/schema/client-api namespace such as:

<message xmlns="jabber:client" 
         from="(athena|zeus)@agents.notify.me/agent" 
         to="foo@bar.com" 
         xml:lang="en">
  <nm:data xmlns:nm="http://notify.me/schema/client-api">
    <nm:notifications>
      <nm:notification-group>
        <nm:from>someone</nm:from>
        <nm:notification>
          <nm:body>message from someone 1</nm:body>
          <nm:url>http://foo.com/</nm:url>
        </nm:notification>
        <nm:notification>
           <nm:body>message from someone 2</nm:body>
          <nm:url>http://foo.com/</nm:url>
        </nm:notification>
      </nm:notification-group>
      <nm:notification-group>
        <nm:from>someone else</nm:from>
        <nm:notification>
          <nm:body>message from someone else 1</nm:body>
          <nm:url>http://foo.com/</nm:url>
        </nm:notification>
      </nm:notification-group>
    </nm:notifications>
  </nm:data>
  <x xmlns="jabber:x:delay" stamp="20080928T06:37:03" />
</message>

XML-RPC Calls

<iq type='set'
    from="{sender@host/resource}"
    to="(athena|zeus)@agents.notify.me/{resource}"
    id='{call-id}'>
    <query xmlns='jabber:iq:rpc'>
    	   <methodCall>
	   <methodName>sources.add</methodName>
		<params>
			<param>
				<value>{uri to add}</value>
			</param>
		</params>
        </methodCall>
    </query>
</iq>

<iq type='result' 
    from="(athena|zeus)@agents.notify.me/{resource}" 
    to="{sender@host/resource}" 
    id='{call-id}'>
    <query xmlns='jabber:iq:rpc'>
        <methodResponse/>
    </query>
</iq>

<iq type='error' 
    from="(athena|zeus)@agents.notify.me/{resource}" 
    to="{sender@host/resource}" 
    id='{call-id}'>
    <query xmlns='jabber:iq:rpc'>
        <methodCall>
            <methodName>sources.add</methodName>
            <params>
                <param>
                    <value>{uri to add}</value>
                </param>
                </params>
        </methodCall>
    </query>
    <error code='400' type='modify'>
        <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    </error>
</iq>