Version0API

About the API

This is the Version 0 "API" for Identi.ca (and Laconi.ca). We're working on a "real" API, but for now this is the way to read and write to Identi.ca programmatically.

We will eventually be closing the write access by various means. It's not particularly clean or safe. However, the documented write API below will remain available until at least September 30, 2008.

Formats

Most of the existing API consists of RDF data, encoded as XML. You may have a more pleasing experience working with an RDF parser directly, rather than a simple XML parser.

Reading notices

Each user has four "RSS 1.0" streams associated with their account.

• `http://identi.ca/username/rss` -- A stream of the notices by a user.
• `http://identi.ca/username/all/rss` -- A stream of the notices by a user and people they subscribe to ("and friends")
• `http://identi.ca/username/replies/rss` -- A stream of the notices sent to a user using the "@username" convention.
• `http://identi.ca/tag/tagname/rss` -- A stream of notices tagged with the "#tagname" convention.

You can get more or fewer notices by adding a "limit=number" argument to any of these RSS feeds.

There are no direct messages in Laconica (yet), so there is no way to retrieve direct messages.

Social connections

Each user has a FOAF file associated with their account, which can be used to trace social connections.

• `http://identi.ca/username/foaf` -- Social connections

In this file, "X knows Y" means that user X is subscribed to user Y's notices. "Y knows X" is the reverse relationship. This is a little out of the strict sense of "knows" in the FOAF definition.

Avatars

Not yet functional

Each user has 4 avatars associated with their account.

• `http://identi.ca/username/avatar/original` -- Original photo uploaded for use with their account; can be any size
• `http://identi.ca/username/avatar/96` -- A 96x96 pixel square avatar, based on the original
• `http://identi.ca/username/avatar/48` -- A 48x48 pixel square avatar, based on the original
• `http://identi.ca/username/avatar/24` -- A 24x24 pixel square avatar, based on the original

Even if the user hasn't uploaded an avatar, a default avatar at the correct size will be made available at these URLs. Be prepared for a redirect: the actual files are located elsewhere, so be ready for a "302 Found" with the correct location.

File format depends on the original upload; it's going to be a PNG, GIF, or JPEG file.

Posting notices

Posting notices depends on having a cookie-aware HTTP library.

Posting a notice takes two steps:

Login

You have to have a valid login cookie to post. To get one, send an HTTP POST to `http://identi.ca/main/login` with the arguments `nickname` and `password`.

Post notice

Once you have login cookies, you can post notices. To send one, submit an HTTP POST message to `http://identi.ca/notice/new` with the argument `status_textarea`, a string of maximum 140 characters.

Example code

• "A perl script" by DonMarti that posts to both identi.ca and twitter.
• "Identica interface for Gwibber" by segphault
• "Simple command line read/update script for Identica" by psykoyiko
• "Yet another simple Command Line tool and Python module for ident.ca" by zeth

A python script to post a notice to identi.ca:

#!/usr/bin/env python2.4
#
# by Ryan Paul (http://identi.ca/segphault)
#
import urllib, urllib2

username = "yourusername"
password = "yourpassword"

opener = urllib2.build_opener(urllib2.HTTPCookieProcessor())

opener.open(urllib2.Request("http://identi.ca/main/login",
  urllib.urlencode({"nickname": username, "password": password}))).read()

print opener.open(urllib2.Request("http://identi.ca/notice/new",

  urllib.urlencode({"status_textarea": "Posting a test notice from Python"}))).read()

A PHP function using the PEAR package HTTP_Request to post to a laconica server:

/**
 * Sent a message to a laconica server
 * By Mike Cochrane http://mikenz.geek.nz
 */
function sendMessage($message, $login, $password, $server = 'http://identi.ca') {
    require_once "HTTP/Request.php";

    /* Login */
    $req = new HTTP_Request($server . '/main/login');
    $req->setMethod(HTTP_REQUEST_METHOD_POST);
    $req->addPostData("nickname", $login);
    $req->addPostData("password", $password);
    $req->sendRequest();
    $cookies = $req->getResponseCookies();

    /* Send message */
    $req->setURL($server . '/notice/new');
    foreach ($cookies as $c) {
        $req->addCookie($c['name'], $c['value']);
    }
    $req->clearPostData();
    $req->addPostData("status_textarea", $message);
    $req->sendRequest();
}

Links

• Redland -- an RDF library (including RDF parsing) with bindings for many programming languages