Twitter-compatible API
The goal of the Twitter-ish API is to make it extremely easy for developers with tools that already talk to Twitter to communicate with Laconica sites as well. The most used methods will be implemented first.
The official Twitter API wiki is a good place to start for information about this API. We intend to provide full documentation on this site, but for now will have the exceptions. The following will be mostly useful for devs experienced with the Twitter API and getting ready to build in Identi.ca compatibility.
API root
The API root for identi.ca is at http://identi.ca/api.
To make API calls you tack on the method name. Examples:
http://identi.ca/api/statuses/public_timeline.xml http://identi.ca/api/statuses/show/123.xml http://identi.ca/api/friendships/exists.json?user_a=bob&user_b=doug
For other Laconica installs, the API root will be determined by whatever you set your $config['site']['server'] and $config['site']['path'] variables to in config.php. Generally, the pattern is:
http://$config['site']['server']/$config['site']['path']/api
So if your site server name is www.gar.org and the path to your Laconica install is laconica, your API root will be:
http://www.gar.org/laconica/api
Authentication
As with Twitter, the API uses HTTP Basic Authentication. Note that this means that users with only an OpenID login cannot use the API; they have to add a password to their account using the control panel on the site.
There’s no support for other, undocumented authentication methods.
JSONP callbacks
For API methods that return JSON, an optional JSONP-style callback parameter is supported. If supplied, the response will be in JSONP format with a callback of the given name. (Note: this is actually an undocumented feature of Twitter’s API.)
http://identi.ca/api/statuses/public_timeline.json?callback=foo
Rate limiting
We currently don’t enforce any rate-limiting. Please don’t make us regret it.
Gotchas
Some things to remember:
- Laconi.ca supports OpenMicroBlogging and some notices and friends may come from other servers.
- On Laconi.ca sites, user nicknames are unique, but they are not globally unique. Use the ID number instead.
- Private streams are not implemented on Laconi.ca yet.
Status methods
| Public timeline | As documented, except: does not support ‘since’ parameters. |
| Friends timeline | As documented, except: does not support the ‘since’ parameter. |
| User timeline | As documented, except: does not support the ‘since’ parameter. |
| Show | As documented. |
| Update | As documented, including support for ‘in_reply_to_status_id’ parameter. |
| Replies | As documented, except: does not support the ‘since’ parameter. |
| Destroy | As documented. |
Note: As of Laconica 0.6.1, status methods support the ‘since_id’ parameter, which returns statuses with an ID greater than (more recent than) the specified ID. Additionally, they support a ‘before_id’ parameter, which returns all the notices before a given ID. ‘before_id’ is an extension to Twitter’s API.
User methods
| Friends | As documented, except: does not support the ‘since’ or ‘lite’ parameters. Also, ordered by subscription and not signup date. |
| Followers | As documented, except: does not support the ‘since’ or ‘lite’ parameters. Also, ordered by subscription and not signup date. |
| Featured | Not implemented. Robert Scoble gets too much attention as it is. |
| Show | As documented. However, if the user cannot be found, a 404 error will be returned, unlike Twitter, which returns a random(?) user in that event. Also, you can bring up a user by email address alone. A user id is not required if an email address is supplied. |
Direct message methods
Supported as of Laconica 0.6.1.
| direct_messages | As documented, except: does not support the ‘since’ and ‘since_id’ parameters. |
| sent | As documented, except: does not support the ‘since’ and ‘since_id’ parameters. |
| new | As documented. |
| destroy | Not implemented. |
Friendship methods
| create | As documented. Note that users cannot subscribe to remote profiles using this API. |
| destroy | As documented. Users can unsubscribe to a remote profile using this API, but it’s preferred to use numeric IDs to nicknames. |
| exists | As documented. |
Account methods
| verify_credentials | As documented. |
| end_session | Not implemented. |
| update_location | As documented. |
| update_delivery_device | Not implemented. |
| rate_limit_status | Not implemented. |
Favorite methods
Supported as of Laconica 0.6.1.
| favorites | As documented. |
| create | As documented. |
| destroy | Not implemented. |
Notification methods
| follow | Not implemented. |
| leave | Not implemented. |
Block methods
Laconica does not support blocks yet.
| create | Not implemented. |
| destroy | Not implemented. |
Help methods
| test | As documented. |
| downtime_schedule | Not implemented. |