Twitter-compatible API

From StatusNet
Revision as of 03:22, 23 June 2012 by Yvolk (Talk | contribs)
Jump to: navigation, search

Contents

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

Authentication

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:

  • 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 
--> http://www.gar.org/statusnet/index.php/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.

Timeline resources

statuses/public_timeline As documented.
statuses/home_timeline Fully compatible with enhancements.
statuses/friends_timeline Alias of home_timeline.
statuses/mentions Fully compatible with enhancements.
statuses/replies Alias of mentions.
statuses/user_timeline As documented.
statuses/retweeted_to_me Not implemented yet.
statuses/retweeted_by_me Not implemented yet.
statuses/retweets_of_me As documented.

Status resources

statuses/show As documented.
statuses/update As documented. Additional 'media' parameter allows binary multimedia uploads (images, etc.). Format post data as multipart/form-data when using the 'media' parameter.
statuses/destroy As documented.
statuses/retweet As documented. Note: we call these repeats in the web interface.

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 #Gotchas

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.

User resources

statuses/friends As documented, except: does not support 'lite' parameter. Also, ordered by subscription and not signup date.
statuses/followers As documented, except: does not support 'lite' parameter. Also, ordered by subscription and not signup date.
users/show As documented. Additionally, you can bring up a user by email address alone. A user id is not required if an email address is supplied.

Direct message resources

Supported as of StatusNet 0.6.1.

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

Friendships resources

friendships/create As documented. Note that users cannot subscribe to remote profiles using this API.
friendships/destroy As documented. Users can unsubscribe to a remote profile using this API, but it's preferred to use numeric IDs to nicknames.
friendships/exists As documented.
friendships/show As documented.

Friends and followers resources

Supported as of StatusNet 0.7.2.

friends/ids As documented.
followers/ids As documented.

Account resources

account/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).
account/end_session Not implemented.
account/update_location As documented.
account/update_delivery_device Not implemented.
account/rate_limit_status We have no rate limit, so this always returns 150 hits left.
account/update_profile_background_image As documented.
account/update_profile_image As documented.

Favorite resources

Supported as of StatusNet 0.6.1.

favorites As documented.
favorites/create As documented.
favorites/destroy As documented.

Notification resources

notifications/follow Not implemented.
notifications/leave Not implemented.

Block resources

Supported as of StatusNet 0.6.4.

blocks/create As documented.
blocks/destroy As documented.
blocks/exists Not implemented yet.
blocks/blocking Not implemented yet.

Help resources

help/test As documented.

OAuth resources

oauth/request_token As documented.
oauth/authorize As documented.
oauth/access_token As documented.

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=<query>

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:

Trends

StatusNet does not support search term trending data, yet.

StatusNet resources

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

Group resources

statusnet/groups/timeline GET Shows a group's timeline. Similar to other timeline resources. params: page (int), count (int), max_id (int), since_id (int), format (string, 'xml', 'json', 'atom', or 'rss'), callback (string, JSON-P callback) [format is required]
statusnet/groups/show GET Show a groups profile. params: id (string, group ID or nickname), group_id (int), group_name (string), format (string, 'xml' or 'json'), callback (string, JSON-P callback) [format is required; must also include a param identifying a group]
statusnet/groups/create POST Create a new group. params: nickname (string, name of the group), full_name (string), homepage (string), description (string), location (string), aliases (string, comma-separated), format (string, 'xml' or 'json'), callback (string, JSON-P callback function) [format and nickname are required]
statusnet/groups/join POST Join a group. params: id (string, group ID or nickname), group_id (int), group_name (string), format (string, 'xml' or 'json'), callback (string, JSON-P callback) [format is required; must also include a param identifying a group]
statusnet/groups/leave POST leave a group. params: id (string, group ID or nickname), group_id (int), group_name (string), format (string, 'xml' or 'json'), callback (string, JSON-P callback) [format is required; must also include a param identifying a group]
statusnet/groups/list GET Show the groups a given user is a member of. params: id (string, user ID or nickname), user_id (int), screen_name (string), format (string, 'xml' or 'json'), callback (string, JSON-P callback) [format is required; must also include a param identifying a user]
statusnet/groups/list_all GET List all local groups. params: page (int), count (int), format (string, 'xml', 'json', 'atom', or 'rss'), callback (string, JSON-P callback) [format is required]
statusnet/groups/membership GET List the members of a given group. params: id (string, group ID or nickname), group_id (int), group_name (string), format (string, 'xml' or 'json'), callback (string, JSON-P callback) [format is required; must also include a param identifying a group]
statusnet/groups/is_member GET Determine whether a given user is a member of a given group. params: id (string, user ID or nickname), user_id (int), group_id (int), screen_name (string), group_name (string), format (string, 'xml' or 'json'), callback (string, JSON-P callback) [format is required; must also include a param identifying a user, and a param identifying a group]

Tag resources

statusnet/tags/timeline Shows a tag's timeline. Similar to other timeline resources.

Media resources

statusnet/media/upload Twitpic-style endpoint for uploading an image. Returns a URL that can be used in a status update. Format post data as multipart/form-data.

statusnet/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>Identi.ca</name>
  <server>identi.ca</server>
  <theme>identica</theme>
  <path></path>
  <logo>http://theme.status.net/0.9.3/identica/logo.png</logo>

  <fancy>true</fancy>
  <language>en</language>
  <email>admin@status.net</email>
  <broughtby>Status.net</broughtby>
  <broughtbyurl>http://status.net/</broughtbyurl>
  <timezone>UTC</timezone>

  <closed>false</closed>
  <inviteonly>false</inviteonly>
  <private>false</private>
  <textlimit>140</textlimit>
  <ssl>sometimes</ssl>
  <sslserver>identi.ca</sslserver>

  <shorturllength>30</shorturllength>
</site>
 <license>
  <type>cc</type>
  <owner></owner>
  <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>stav,tuxbrain,scobleizer,jra,jargon,timbl,remindme,lh,diveintomark,storming,cmdln,jzb,robmyers,burncast,transmediale,bluegrasspoet,linuxfoundation</featured>
</nickname>
 <profile>
  <biolimit></biolimit>
</profile>
 <group>

  <desclimit></desclimit>
</group>
 <notice>
  <contentlimit></contentlimit>
</notice>
 <throttle>
  <enabled>true</enabled>
  <count>20</count>
  <timespan>600</timespan>

</throttle>
 <xmpp>
  <enabled>true</enabled>
  <server>identi.ca</server>
  <port>5222</port>
  <user>update</user>
</xmpp>
 <integration>

  <source>identica</source>
</integration>
</config>

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: 

<?xml version="1.0" encoding="UTF-8"?>
<version>0.9.3</version>
Retrieved from "http://status.net/wiki/index.php?title=Twitter-compatible_API&oldid=22445"
Personal tools
Namespaces
Variants
Actions
Navigation
Status.net
Toolbox