Documentation

Authentication
Fancy Urls
JSON
XML-RPC
The Calls

Devku @ Jaiku.com

Jaiku Developer Documentation

Authentication

How to use` it

For any of the urls on the site you can add your login credentials to the request by including

?user=$user&personal_key=$personal_key

If you are posting please remember to include them in the post arguments instead of in the url.

If you are posting via XML-RPC remember to include the login credentials as key-value pairs in the dictionairy sent to the server.

Fancy Urls

On some good advice we have designed most of our api around the idea that things on the web should look like things on the web, that the unique identifier for something should be the same unique identifier that we are all familiar with, its url.

Throughout the next set of urls, wherever possible we have returned the pplicable url to further your queries. Whenever you see a user, you will also see the url at which more information about that user can be located.

Public Stream

jaiku.com/feed/(json|rss|atom)              # no auth required

User's Stream

$user.jaiku.com/feed/(json|rss|atom)        # no auth for public

User Infomation

$user.jaiku.com/json                        # json only for now
                                            # no auth for public

Current Presence

This is different from the latest update as it has more up-to-date information about things like location, this is what the badges use.

$user.jaiku.com/presence/(json|xml)         # no auth for public

The xml is in a proprietary format that looks a bit like this:

<presence>
    <line>My latest Jaiku</line>
    <location>
        <neighbourhood>jaiku World HQ/neighborhood>
        <city>Helsinki</city>
        <country>Finland</country>
    </location>
    <near>
        <contacts>3</contacts>
        <others>0</others>
    </near>
    <profile>Silent</profile>
    <user nick="jaiku" first_name="Jaiku" last_name="Team"
          avatar="http://jaiku.com/image/1/avatar_15_t.jpg"
          url="http://jaiku.jaiku.com" />
</presence>

Last Stream Entry

Redirects to the user's last stream entry in the desired format.

$user.jaiku.com/presence/last/(json|xml)    # actor's last update
                                            # (will redirect to a url
                                            # like the one below)

An Individual Stream Entry

This is the relevant data about an individual entry

$user.jaiku.com/presence/$item/(json|atom)  # no auth for public

The JSON Interface

The JSON interface operates over simple POST calls to

api.jaiku.com/json

and should include the authentication parameters as well as the method parameter.

An example request:

POST /json
user=jaiku&personal_key=12345678901234&method=test&echo=Hello

And the response:

{"status": "ok", "echo": "Hello"}

The XML-RPC Interface

The XML-RPC interface uses... well... xml-rpc. You'll be using a library, surely. The endpoint for requests is:

api.jaiku.com/xmlrpc

All parameters should be sent as a dictionary, which means one big argument that is a list of key-value pairs rather than positional arguments (this makes it easier to deal with defaults)

An example call (from python):

>>> from xmlrpclib import ServerProxy
>>> s = ServerProxy("http://api.jaiku.com/xmlrpc")
>>> s.test({"user": "jaiku", "personal_key": "12345678901234",
...         "echo": "Hello"})
{"status": "ok", "echo": "Hello"}

The Calls

All calls exist in both interfaces unless otherwise specified.

And there's only one right now...

presence.send

Send a presence update to jaiku

auth_required
(bool) generated # optional, default false
                 # yes means to ignore processing this into your stream
                 # and simply update the presence, us this for things
                 # that are generated automatically, for example the
                 # current weather
                 # people don't get notifications about generated updates

(str) message    # this is the message to send, if the generated flag
                 # is not set it will be processed pretty much the same
                 # as something that was sent via the web, sms or from
                 # the mobile client
                 # will be truncated after 140 characters

(int) icon       # optional, default 300
                 # the id of the icon to associate with this update,
                 # at some point we'll probably hook up keywords to these
                 # so you'll be able to send a symbolic name, too

(str) location   # optional
                 # the location to associate this update with, we'll try
                 # to parse things according to something like the
                 # following:
                 #   r'^(?P<neighborhood>[^,]+), (?P<city>[^,]+), (?P<country>[^,]+)$'
                 #   r'^(?P<city>[^,]+), (?P<country>[^,]+)$'
                 #   r'^(?P<whatever>[^,]+)$'
                 #    ^-- we'll try to match it to a country first,
                 #        otherwise we'll just post it as is

returns -->

OK on success

one of the general errors on failure