Twitter-compatible API

From StatusNet

Jump to: navigation, search

Contents

[edit] 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 StatusNet 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.

[edit] 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 StatusNet installs, the API root will be determined by whatever you set your $config['site']['path'] and $config['site']['server'] 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 StatusNet install is statusnet, your API root will be: 

http://www.gar.org/statusnet/api

[edit] 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.

Note: As of Tuesday, Feb 10, 2009, Identi.ca officially supports SSL for all API methods, and it's especially recommended for use with API methods requiring authentication (e.g.: https://identi.ca/api/account/verify_credentials.xml).


[edit] 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

[edit] Rate limiting

We currently don't enforce any rate-limiting. Please don't make us regret it.

[edit] Gotchas

Some things to remember:

  • StatusNet supports OpenMicroBlogging and some notices and friends may come from other servers.
  • On StatusNet sites, user nicknames are unique, but they are not globally unique. Use the ID number instead.
  • Private streams are not implemented in StatusNet yet.
  • StatusNet sites can be configured as private. In that case, all API methods require authentication, including the public timeline (see the 'config' method below).

[edit] Status methods

Public timeline As documented.
Friends timeline Fully compatible with enhancements.
User timeline As documented.
Show As documented.
Update As documented, including support for 'in_reply_to_status_id' parameter. Additional 'media' parameter allows binary multimedia uploads (images, etc.). Format post data as multipart/form-data when using the 'media' parameter.
Replies Fully compatible with enhancements.
Destroy As documented.

Note: As of StatusNet 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. Update 06/01/09 - As of 0.7.4 'before_id' has been changed to 'max_id', because Twitter has implemented this feature as max_id.

The original Twitter API allows Friends timeline and Replies only for the currently authenticated user. StatusNet supports these methods for arbitrary users. The paths are api/statuses/friends_timeline/[username].rss and api/statuses/replies/[username].rss.

[edit] User methods

Friends As documented, except: does not support 'lite' parameter. Also, ordered by subscription and not signup date.
Followers As documented, except: does not support 'lite' parameter. 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.

[edit] Direct message methods

Supported as of StatusNet 0.6.1.

direct_messages As documented.
sent As documented.
new As documented.
destroy Not implemented.

[edit] 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.

[edit] Social Graph methods

Supported as of StatusNet 0.7.2.

ids (friends) As documented.
ids (followers) As documented.

[edit] Account methods

verify_credentials As documented. Note: as of StatusNet 0.6.4, this method returns a full user profile upon successful authentication (Twitter started doing this on Dec 10th, 2008).
end_session Not implemented.
update_location As documented.
update_delivery_device Not implemented.
rate_limit_status Implemented in 0.7.4 - We have no rate limit, so this always returns 100 hits left.

[edit] Favorite methods

Supported as of StatusNet 0.6.1.

favorites As documented.
create As documented.
destroy Not implemented.

[edit] Notification methods

follow Not implemented.
leave Not implemented.

[edit] Block methods

Supported as of StatusNet 0.6.4.

create As documented.
destroy As documented.

[edit] Help methods

test As documented.
downtime_schedule Not implemented.

[edit] Search

StatusNet has a Twitter-compatible notice search as of StatusNet 0.7.1, and search results can be returned in both Atom and JSON formats.

[edit] Atom

To request search results in Atom, append your URL-encoded query as a parameter to the search method and specify the Atom format: 

http://identi.ca/api/search.atom?q=<query>

[edit] JSON

To request search results in JSON, append your URL-encoded query as a parameter to the search method and specify the JSON format: 

http://identi.ca/api/search.json?q=<query>

The search method also supports the following optional URL parameters:

Other things to note:

  • StatusNet's version of the search does not support operators, such as "from:", "to:" and booleans, yet.
  • Notice content is HTML-encoded.

Example searches:

[edit] Trends

StatusNet does not support search term trending data, yet.

[edit] StatusNet methods

These are extensions to the Twitter API that expose StatusNet-specific functionality.

[edit] config

Show a StatusNet instance's configuration info. Of special note is the <private> element (config/site/private), which indicates whether a StatusNet site is private. When a site is configured as private every other API method requires authentication, including the public timeline (`/api/statuses/public_timeline.format`).

  • URL: `/api/statusnet/config.format`
  • Method: GET
  • Auth required: no
  • Parameters: None
  • Formats: xml, json
  • Returns: configuration information

Example ruby script showing how to test for 'private' mode.

Example XML return document: 

<?xml version="1.0" encoding="UTF-8"?>
<config>
 <site>
  <name>StatusNetts</name>
  <server>statusnetts.org</server>
  <theme>statusnett</theme>
  <path>statusnetts</path>
  <fancy>true</fancy>
  <language>en_US</language>
  <email>admin@statusnetts.org</email>
  <broughtby>StatusNetts, Inc.</broughtby>
  <broughtbyurl>http://loconicats.net/blog</broughtbyurl>
  <closed>false</closed>
  <inviteonly>false</inviteonly>
  <private>true</private>
</site>
 <license>
  <url>http://creativecommons.org/licenses/by/3.0/</url>
  <title>Creative Commons Attribution 3.0</title>
  <image>http://i.creativecommons.org/l/by/3.0/80x15.png</image>
</license>
 <nickname>
  <featured>little_cat_A,catinthehat</featured>
</nickname>
 <throttle>
  <enabled>false</enabled>
  <count>20</count>
  <timespan>600</timespan>
</throttle>
 <xmpp>
  <enabled>false</enabled>
  <server>INVALID SERVER</server>
  <user>update</user>
</xmpp>
</config>

[edit] version

Show the version of StatusNet an instance is running.

  • URL: `/api/statusnet/version.format`
  • Method: GET
  • Auth required: no
  • Parameters: None
  • Formats: xml, json
  • Returns: version information

Example XML return document: 

<?xml version="1.0" encoding="UTF-8"?>
<version>0.7.1</version>
Retrieved from "http://status.net/wiki/Twitter-compatible_API"
Personal tools