Twitter-compatible API

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 documentation 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 StatusNet compatibility.

API root
The API root for identi.ca is at http://identi.ca/api. However, there is no resource at the API root. (Twitter's root, http://api.twitter.com/, just shows the home page for Twitter.)

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

HTTP Basic 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.

OAuth authentication
StatusNet supports OAuth 1.0a authentication for API resources. Generally, StatusNet's UI and API are similar to Twitter's for OAuth applications. (If you're new to OAuth check out Beginner’s Guide to OAuth.) To use OAuth with a StatusNet site, you'll need to register your client application via the web interface and obtain a consumer key and secret. You can find the interface for application registration under settings/oauthapps. E.g.:

http://identi.ca/settings/oauthapps

SSL
Identi.ca 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).

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. To make it easier for clients to handle error conditions, HTTP error codes are suppressed, and the errors will be returned in the response body when using JSONP.

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:

--> http://www.gar.org/statusnet/index.php/api )
 * StatusNet supports the OStatus federation protocol (as well as OpenMicroBlogging for backwards compatibility), so many notices and friends' profiles 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).
 * If your apache does not have "Fancy URLs" enabled, the example url's from above need to change. (e.g. http://www.gar.org/statusnet/api
 * The since_id parameter does not work as documented by Twitter. Twitter says of since_id: "There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available." However, StatusNet will return the newest notices (or the newest back from max_id, if present)!! Also, a since_id <= 0 will be ignored.

Status resources
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. See note about since_id under

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.

Direct message resources
Supported as of StatusNet 0.6.1.

Friends and followers resources
Supported as of StatusNet 0.7.2.

Favorite resources
Supported as of StatusNet 0.6.1.

Block resources
Supported as of StatusNet 0.6.4.

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.

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=

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=

The search method also supports the following optional URL parameters:


 * callback: if supplied when using the JSON format, the response will use the JSONP format with a callback of the given name.
 * E.g.:
 * http://identi.ca/api/search.json?callback=foo&q=identica
 * rpp: the number of notices to return per page, up to a max of 100.
 * E.g.:
 * http://identi.ca/api/search.atom?q=gar&rpp=15
 * page: the page number (starting at 1) to return.
 * since_id: returns notices with ids greater than the given id. (NOTE: not yet implemented, see http://status.net/open-source/issues/1987)

Other things to note:


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

Example searches:


 * Find notices containing a word:
 * http://identi.ca/api/search.atom?q=statusnet
 * Find notices referencing a user:
 * http://identi.ca/api/search.atom?q=%40evan
 * Find notices containing a hashtag:
 * http://identi.ca/api/search.atom?q=%23linux

Trends
StatusNet does not support search term trending data, yet.

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

statusnet/config
Show a StatusNet instance's configuration info. Of special note is the &lt;private&gt; 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:

 Identi.ca  identi.ca   identica http://theme.status.net/0.9.3/identica/logo.png

true en  admin@status.net Status.net http://status.net/ UTC

false false false 140  sometimes identi.ca

30  cc   http://creativecommons.org/licenses/by/3.0/ Creative Commons Attribution 3.0

http://i.creativecommons.org/l/by/3.0/80x15.png stav,tuxbrain,scobleizer,jra,jargon,timbl,remindme,lh,diveintomark,storming,cmdln,jzb,robmyers,burncast,transmediale,bluegrasspoet,linuxfoundation

true 20  600

true identi.ca  5222 update

statusnet/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:

 0.9.3