Printable versionThis section explains how to use the Simple Update Protocol (SUP) to monitor user activity feeds for YouTube users. This functionality will likely be most appealing to sites that maintain their own friend graphs or that want to monitor the activities of many users.
At a general level, SUP enables an API provider (such as YouTube) to notify API users when a feed is updated. SUP is particularly useful for API users that want to monitor many different feeds at once. With SUP, an API user can issue a single query to identify all updated resources, which is a much more efficient way to monitor changes than frequent polling. The API user can then retrieve data only for the modified resources, eliminating the need to ever issue polling requests on unchanged resources.
The following sections explain how to use SUP to monitor user activity feeds:
An SUP feed consists of a JSON object that maps the keys in the list below to their corresponding values:
The since_time field specifies the earliest time that a resource could have changed and still have been included in the SUP feed.
The updated_time field specifies the latest time that a resource could have changed and still have been included in the SUP feed. As such, the feed identifies resources that were updated within the inclusive time range beginning at the since_time and ending at the updated_time.
The period field specifies the duration of the time interval for which the SUP feed includes updates. As defined in the SUP specification, the number of seconds between between the since_time and the updated time must be equal to or greater than the interval that the period field specifies.
The available_periods field contains a map that identifies the different SUP available for a feed. The map key contains a number that specifies the length of time (period) for which the corresponding feed contains updates. The value associated with the map key specifies the feed URL.
The updates field contains an array of two-element lists, where the first element identifies an updated resource and the second element is a string used to distinguish between updates. In YouTube's SUP feed, this field identifies updated user activity feeds.
The sample SUP feed below contains updates for a five-minute (300 second) period and indicates that feeds are also available covering updates that occurred within 10-minute or 15-minute periods.
{ "updated_time": "2009-04-28T21:29:20Z",
"since_time": "2009-04-28T21:24:19Z",
"period": 300,
"available_periods": {
"300": "http://gdata/youtube.com/sup?seconds=300",
"600": "http://gdata/youtube.com/sup?seconds=600",
"900": "http://gdata/youtube.com/sup?seconds=900"
},
"updates": [
["159aa827", "6e19"],
["9559d1d", "6e19"],
["159aa827", "6f22"],
...
]
}
To retrieve YouTube's SUP feed, send an HTTP GET request to the following URL. Note that you can also use the seconds parameter to retrieve a feed that identifies all of the activity feeds that changed within a specific time interval. The SUP feed's available_periods field identifies the supported time intervals and their associated feed URLs.
http://gdata.youtube.com/sup
In YouTube's SUP feed, each item in the updates array is a two-element list that identifies an updated user activity feed:
To use the SUP feed, you also need to discover the hash keys that YouTube has assigned to the user activity feeds that you want to monitor. You can then determine whether any of those feeds were updated by matching the hash keys in your database to the hash keys in the SUP feed.
To locate the hash key for a particular user's user activity feed, you need to retrieve the user's activity feed from the following URL. (Replace the text username with the user's YouTube username.)
http://gdata.youtube.com/feeds/api/users/username/events?v=2
You can also retrieve the user activity feed for the currently logged-in user by sending an HTTP GET request to the following URL. Note that for this request, you need to provide an authentication token in the Authorization HTTP request header.
http://gdata.youtube.com/feeds/api/users/default/events?v=2
In the API response, the <feed> tag will contain a <link> tag for which the rel attribute value is updates. That href attribute contains a link to YouTube's SUP feed, and the link embeds the hash key that uniquely identifies the activity feed.
<link rel='updates' type='application/json' href='http://gdata.youtube.com/sup?seconds=300#47677e0a'/>
The Über Activity Viewer, a sample application demonstrated at Google I/O 2009, uses SUP to monitor the activities of participating YouTube users.
The application has two main components:
A Java daemon periodically fetches YouTube's SUP feed and checks to see whether any participating users (members) are identified in the feed. The daemon creates multiple threads to retrieve updated activity feeds and store the updates in a database.
A PHP website retrieves a list of activities from the database and then sends API requests to retrieve additional metadata about each activity. For example, while the Java daemon records that an event, such as a user added a favorite video or a friend, the PHP application retrieves metadata about the video or the new friend's profile. The PHP application also lets new users join the Über Activity Viewer user list, retrieving the SUP user hash for each new user and storing the hash and YouTube username in the database.
You can download sample code for the Über Activity Viewer at http://code.google.com/p/gdata-samples/source/browse/#svn/trunk/uberviewer.
Watch a video of Jeff Fisher and Jochen Hartmann explaining SUP and presenting the Über Activity Viewer at Google I/O 2009. (The part of the presentation that covers SUP begins at the 23:38 mark of the video.)
