|
ApiDocumentation
FriendFeed API DocumentationTable of Contents
IntroductionThe FriendFeed API enables developers interact with the FriendFeed web site programmatically via simple HTTP requests. This is the technical documentation for the API. Other important links:
Core ConceptsRequests and Data FormatsAll requests to the FriendFeed API are simple HTTP GET and POST requests. For example, you can fetch the JSON version of the most recent 30 public entries published to FriendFeed by fetching http://friendfeed.com/api/feed/public. All of the API requests that output feeds are available in four formats: JSON, a simple form of XML, RSS 2.0, and Atom 1.0. JSON is the default output format. To request a different output format, simply add an format= argument to the URL:
The other API requests, like posting a new comment on an entry, only support the JSON and XML output formats since they do not output feed-oriented data. AuthenticationIf you are publishing data to FriendFeed or if you are requesting the feed that includes data from a user with a private feed, your HTTP requests must be authenticated. All FriendFeed users have a Remote Key to provide third party applications access to their FriendFeed. A FriendFeed Remote Key is just like a password, except that it is only used for third party applications, so it only provides access to the functionality defined by the API. Users can easily reset it if a third party application abuses the API. All requests that require authentication use HTTP Basic Authentication. The username should be the user's nickname, and the password should be the user's Remote Key. You can direct user's to http://friendfeed.com/remotekey to get their remote key if they have not memorized it. See the FriendFeed API Application Guidelines for a complete set of recommendations of how to present authentication in your application. The Python and PHP libraries available at http://code.google.com/p/friendfeed-api/ implement authentication for all methods that require it. Note: We are currently exploring adding OAuth support as well. If you are interested in this support, let us know in the FriendFeed developer forum. JSON CallbacksThe JSON output format supports an additional argument callback= that wraps the JSON output in a function call to a function of your choice. This functionality is available to enable you to use the API with JavaScript within a web browser. For example, http://friendfeed.com/api/feed/public?callback=foo outputs: foo({"entries":[...]})Using JSON and callbacks, you can place the FriendFeed API request inside a <script> tag, and operate on the results with a function elsewhere in the JavaScript code on the page. All authentication is ignored if the callback= argument is given, so JSON callbacks only work with public feeds. ErrorsFriendFeed returns appropriate HTTP status codes for API requests. In addition to the HTTP status code, FriendFeed includes error information in the response body. The error response body is formatted as XML if the requested format is format is xml, rss or atom. Otherwise, the response body is formatted as JSON. The JSON form of an error response has the following format:
The error codes are:
Example error responses using curl: # Title is required field for entries.
$ curl --basic --user nickname:remotekey --data comment=hello \
http://friendfeed.com/api/share
{"errorCode":"title-required"}
# Here's the same error with XML output
$ curl --basic --user nickname:remotekey --data comment=hello \
http://friendfeed.com/api/share?format=xml
<?xml version="1.0" encoding="utf-8"?>
<error><errorCode>title-required</errorCode></error>Reading FriendFeed FeedsOverviewFeed FormatsThe JSON form of the feeds has the following structure:
The simple XML format (output=xml) has the same structure as the JSON. The RSS and Atom formats use the standard RSS and Atom attributes for title, link, published, and updated, and include extension elements for all of the other meta-data. Dates in JSON and dates in the FriendFeed extension elements in the Atom and RSS feeds are in RFC 3339 format in UTC. You can parse them with the strptime string "%Y-%m-%dT%H:%M:%SZ". Filtering & PagingAll of the feed methods below support the following additional arguments:
Methods
/api/feed/user - Fetch Entries from Multiple UsersReturns the most recent entries from a list of users, specified by nickname: http://friendfeed.com/api/feed/user?nickname=bret,paul,jim If more than one nickname is specified, the feed most recent entries from all of the given users. If any one of the users has a private feed, authentication is required. Using the FriendFeed Python library: service = friendfeed.FriendFeed()
feed = service.fetch_multi_user_feed(["bret", "jim", "paul"])
for entry in feed["entries"]:
print entry["title"]You can also specify by email: http://friendfeed.com/api/feed/user?emails=example1@example.com,example2@example.com /api/feed/entry - Fetch Multiple Entries by IDReturns the requested entries, specified by id: Authentication is not required, but private entries will be omitted from unauthenticated results, as will entries the authenticated user does not have permission to view. /api/feed/search - SearchExecutes a search over the entries in FriendFeed. The default scope is over all public entries. http://friendfeed.com/api/feed/search?q=friendfeed The query syntax is the same syntax as http://friendfeed.com/search/advanced. The query operators are:
As a convenience feature you can use "me" in place of any nickname and we will replace it with the authenticated user's nickname: curl -u "nickname:remotekey" http://friendfeed.com/api/feed/search?q=friends:me+friendfeed Using the FriendFeed Python library: service = friendfeed.FriendFeed()
feed = service.search("from:bret friendfeed")
for entry in feed["entries"]:
print entry["title"]
/api/feed/url - Fetch Entries about a URLReturns the most recent entries linking to a given URL. If authentication is used, private entries may be returned, otherwise only public entries will be. When authenticated, the results may be limited to only entries from the user's friends and subscribed rooms by passing subscribed=1: curl -u "nickname:remotekey" \ 'http://friendfeed.com/api/feed/url?url=http://blog.friendfeed.com/2008/12/simple-update-protocol-update.html&subscribed=1' The results may also be limited to a given set of users or rooms by specifying their nicknames: Note that there is a best-effort attempt to resolve URL shorteners, so some entries may contain links that redirect to the specified one. The service filter is not currently supported on this feed. /api/feed/domain - Fetch Entries from a domainReturns the most recent entries linking to URLs in the given domain(s). http://friendfeed.com/api/feed/domain?domain=blog.friendfeed.com,code.google.com By default, sub-domains will not be matched (i.e. friendfeed.com will not include blog.friendfeed.com entries). Subdomain matches may be requested by passing inexact=1 (the results of inexact queries will be unsorted for performance reasons): http://friendfeed.com/api/feed/domain?domain=friendfeed.com&inexact=1 If authentication is used, private entries may be returned, otherwise only public entries will be. When authenticated, the results may be limited to only entries from the user's friends and subscribed rooms by passing subscribed=1: curl -u "nickname:remotekey" \ 'http://friendfeed.com/api/feed/domain?domain=blog.friendfeed.com,code.google.com&subscribed=1' The results may also be limited to a given set of users or rooms by specifying their nicknames: Note that there is a best-effort attempt to resolve URL shorteners, so some entries may contain links that redirect to ones in the specified domain(s). The service filter is not currently supported on this feed. Publishing To FriendFeedAll of the calls to publish information to FriendFeed are HTTP requests. You can perform test calls from a web browser using the HTTP Basic Authentication built into your browser at http://friendfeed.com/static/html/apitest.html. Requests to FriendFeed are rate limited, which, e.g., limits the number and size of thumbnails you can upload in a day. Normal uses should fall well within our rate limits. If you encounter HTTP 403 errors because of rate limits, and you think the limit is erroneous, please let us know in the developer forum. Create New Entries/api/share - Publish Links or MessagesA POST request to /api/share will publish a new entry on the authenticated user's feed. The arguments are:
Example usage with the FriendFeed Python library:
service = friendfeed.FriendFeed(nickname, remote_key)
# Publish a text message
service.publish_message("Testing the FriendFeed API")
# Publish a link
service.publish_link("Testing the FriendFeed API", "http://friendfeed.com/api/")
# Publish a link with thumbnail images
service.publish_link(
title="Testing the FriendFeed API",
link="http://friendfeed.com/api/",
image_urls=[
"http://friendfeed.com/static/images/jim-superman.jpg",
"http://friendfeed.com/static/images/logo.png",
],
)Example usage with curl: curl -u "nickname:remotekey" \ -d "title=Testing+the+FriendFeed+API&link=http://friendfeed.com/" \ http://friendfeed.com/api/share Upload Images with EntriesThe /api/share method can also accept uploaded images encoded as multipart/form-data. This encoding is the standard used for file uploads within web browsers. If any images are uploaded with the /api/share request, the original and the thumbnail are stored on FriendFeed's servers, and the thumbnail is displayed with the entry. By default, the thumbnails will link to the destination link for the entry. If you want each uploaded image to link somewhere else, you can specify the link in the IMAGENAME_link argument. For example, if your uploaded image is POST argument file0, you can specify the link for that thumbnail as file0_link. Comment and Like Entries/api/comment - Add or Edit CommentsA POST request to /api/comment will add a comment or edit an existing comment on a FriendFeed entry. The arguments are:
Example usage from the Python library: service = friendfeed.FriendFeed(nickname, remote_key)
service.add_comment(
entry="550e8400-e29b-41d4-a716-446655440000",
body="Testing the FriendFeed API",
)Example usage with curl: curl -u "nickname:remotekey" \ -d "entry=550e8400-e29b-41d4-a716-446655440000&body=Testing+the+FriendFeed+API" \ http://friendfeed.com/api/comment /api/comment/delete - Delete a CommentA POST request to /api/comment/delete will delete an existing comment. The arguments are:
/api/like - "Like" an EntryA POST request to /api/like will add a "Like" to a FriendFeed entry for the authenticated user.
Example usage from the Python library: service = friendfeed.FriendFeed(nickname, remote_key)
service.add_like("550e8400-e29b-41d4-a716-446655440000")Example usage with curl: curl -u "nickname:remotekey" \ -d "entry=550e8400-e29b-41d4-a716-446655440000" \ http://friendfeed.com/api/like /api/like/delete - Delete a "Like"A POST request to /api/like/delete will delete an existing "Like." The arguments are:
/api/entry/delete - Delete an EntryA POST request to /api/entry/delete will delete an existing entry. The arguments are:
/api/entry/hide - Hide an EntryA POST request to /api/entry/hide will hide an entry. The arguments are:
Get User Profile Information/api/user/NICKNAME/profile - Get services and subscriptionsReturns list of all of the user's subscriptions (people) and services connected to their account (Authentication required for private users): http://friendfeed.com/api/user/bret/profile The returned JSON has the form:
A POST request to /api/user/NICKNAME/profile will change profile fields. The arguments are:
The response for the POST request is the same as the GET request. Example usage with curl: curl -u "nickname:remotekey" \ -d "name=MyNewName" \ http://friendfeed.com/api/user/nickname/profile /api/profiles - Get services and subscriptions for multiple usersReturns subscriptions and services for multiple users. http://friendfeed.com/api/profiles?nickname=bret,jim,paul,sanjeev The returned JSON has the form:
/NICKNAME/picture - Get a user's profile picturehttp://friendfeed.com/bret/picture?size=medium Size can be "small", "medium", or "large". Get Room Profile Information/api/room/NICKNAME/profile - Get room url, description, member informationReturns a list of all of the room's members and the url associated with the room (Authentication required for private rooms): http://friendfeed.com/api/room/friendfeed-news/profile The returned JSON has the following format:
/rooms/NICKNAME/picture - Get a rooms's profile picturehttp://friendfeed.com/rooms/friendfeed-feedback/picture?size=medium Size can be "small", "medium", or "large". Get List Profile Information/api/list/NICKNAME/profile - Get list url, description, member informationReturns a list of all of the list's members and the url associated with the list (Authentication required): http://friendfeed.com/api/list/personal/profile The returned JSON has the following format:
Subscription ManagementThe subscription management methods below require an API key. An API key is a private key that developers can obtain by sending an email to api@friendfeed.com. The API key is required so we can track how these methods are used and curtail abuse. http://friendfeed.com/settings/modifications will contain a list of subscription modifications and will show which API client made the change. Please read the API guidelines before using these methods: http://friendfeed.com/api/guidelines /api/user/NICKNAME/subscribe - Subscribe to a userSubscribe to a user: http://friendfeed.com/api/user/bret/subscribe Unsubscribe from a user: http://friendfeed.com/api/user/bret/subscribe?unsubscribe=1 Example usage with curl: curl -u "username:nickname" -d "apikey=APIKEY" http://friendfeed.com/api/user/bret/subscribe The returned JSON has the format:
/api/room/NICKNAME/subscribe - Subscribe to a roomSubscribe to a room: http://friendfeed.com/api/room/friendfeed-news/subscribe Unsubscribe from a room: http://friendfeed.com/api/room/friendfeed-news/subscribe?unsubscribe=1 Example usage with curl: curl -u "username:nickname" \ -d "apikey=APIKEY" \ http://friendfeed.com/api/room/friendfeed-news/subscribe The returned JSON has the format:
Real-timeThe real-time methods return entry, comment and like updates since a time identified by a token. The methods return recent updates only. To read the complete update stream, clients should use long polling or poll the API using the interval specified in the response. The real-time methods support the following arguments:
The structure of the real-time output is:
The real-time methods are served from the host chan.friendfeed.com (all other methods are served from friendfeed.com).
Miscellaneous Methods/api/validate - Validate a user's remote keyValidates the user's remote key. If the HTTP Basic Authentication nickname and remote key are valid, we return a HTTP 200 status code. Otherwise, we return an HTTP 401 status code. http://friendfeed.com/api/validate /api/services - List all FriendFeed servicesLists all services currently supported by FriendFeed: http://friendfeed.com/api/services The returned JSON has the format:
Obtaining a subset of data using the "include" argumentIf you are only interested in a subset of the data returned from any of our API methods you can provide the "include" argument a list of comma separated values to specify which properties you are interested in. For example to only include Bret's id and services: http://friendfeed.com/api/user/bret/profile?include=id,services This argument is optional. If it is not provided then all properties will be returned. Pre-populated service import formsYou can send your users to a page on FriendFeed with a pre-populated form to make it easy for them to add your service to their feed. For example: http://friendfeed.com/settings/services/digg?username=foo For services that use a URL rather than a username: http://friendfeed.com/settings/services/blog?url=http://example.com/ Optional arguments:
|
