Printable versionThe YouTube Data API enables a user to add, update or delete contacts.
This section explains how to retrieve a feed containing a list of a specific user's contacts.
To request the currently logged-in user's contact list, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.
http://gdata.youtube.com/feeds/api/users/default/contacts?v=2
To request another user's contact list, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://gdata.youtube.com/feeds/api/users/username/contacts?v=2
In the URL above, you must replace the text username with the user's YouTube username.
An API response to a request for a contact list contains a series of <entry> tags. Note that the API returns a maximum of 100 contacts for any given contact feed request even if more contacts match the request parameters. Each entry in a contact feed contains the following information for an individual contact:
The edit URL, which you would use to update or delete the contact. The Identifying feeds related to a feed entry section explains how to identify the edit URL for a feed entry.
The <category> tag indicates whether the contact is a friend or family.
The <yt:username> tag specifies the contact's YouTube username.
The <yt:status> tag indicates the contact's status. This tag only appears if you are retrieving the contacts of the currently authenticated user. This tag will have one of the following values:
The following XML shows a sample API response containing a contact:
<?xml version='1.0' encoding='UTF-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/' xmlns:batch='http://schemas.google.com/gdata/batch' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"Dk4MQX05fyp7ImA9WxRQGUk."'> <id>tag:youtube,2008:user:andyland74:contacts</id> <updated>2008-07-21T17:34:54.371Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#friend'/> <title>Contacts of andyland74</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='alternate' type='application/atom+xml' href='http://www.youtube.com/profile_friends?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?v=2'/> <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?v=2'/> <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts/batch?v=2'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?...'/> <link rel='service' type='application/atomsvc+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?alt=...'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>4</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry gd:etag='W/"Dk4MQX05fyp7ImA9WxRQGUk."'> <id>tag:youtube,2008:user:andyland74:contact:davydanciu</id> <published>2007-10-17T10:45:41.000-07:00</published> <updated>2008-07-21T17:34:54.370Z</updated> <app:edited xmlns:app='http://www.w3.org/2007/app'> 2008-07-21T17:34:54.370Z</app:edited> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#friend'/> <category scheme='http://gdata.youtube.com/schemas/2007/contact.cat' term='Friends'/> <title>davydanciu</title> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/davydanciu?v=2'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile?user=davydanciu'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts/davydanciu?v=2'/> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts/davydanciu?v=2'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:username>davydanciu</yt:username> <yt:status>accepted</yt:status> </entry> <entry> ... </entry> ... </feed>
To add a contact, you will send an API request that identifies two users: the user who is adding the contact and the contact being added. The request can also use the <category> tag to specify whether the contact is being added to the user's list of family or friends. If the request does not specify a category for the contact, then the contact will appear in the user's list of contacts but will not be placed into either the family or friends category.
The following request provides the URL and illustrates the XML format for adding a contact:
POST /feeds/api/users/default/contacts HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" GData-Version: 2 X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/contact.cat" term="Friends"/> <yt:username>CONTACT_ID</yt:username> </entry>
The following list identifies a common use case for adding a contact:
A user watches a video and then adds the video owner as a friend.
This use case begins with a request to retrieve information about a specific video.
After watching the video, the user clicks a link to view the video owner's profile.
Your application submits an API request to retrieve the video owner's profile.
The page on your site that displays information about the video owner displays a link to add the video owner as a friend. If the user clicks this link, then your application submits an API request to http://gdata.youtube.com/feeds/api/users/default/contacts to create the contact. In the request, the <yt:username> tag identifies the YouTube user who is being added as a contact. In addition, the <category> tag's term attribute indicates whether the contact is a friend (term="Friends") or family (term="Family").
To update a contact, submit an HTTP PUT request to the edit url for that contact. The XML excerpt below shows how the edit URL appears in a contact entry:
<entry> <id>http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID</id> ... <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID'/> ... </entry>
The API enables a user to update a contact in two ways:
A user can accept a contact that has a status of requested. To update a contact in this fashion, in your API request, set the value of the <yt:status> tag to accepted as shown in the sample request below. (Similarly, to reject a contact, set the value of the <yt:status> tag to rejected.
Contacts can be categorized as friends or as family. You can use the API to recategorize contacts into either of these groups. If you categorize a contact as a friend, then the <category> tag's value must be Friends. If you categorize a contact as family, then the <category> tag's value must be Family.
The following sample request demonstrates how to update a contact. In the example, the contact is being accepted and classified as family. Please note that in the example, the variable USER_ID refers to the user who is adding the contact and the variable CONTACT_ID refers to the contact being added.
PUT /feeds/api/users/USER_ID/contacts/CONTACT_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" GData-Version: 2 X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <category scheme="http://gdata.youtube.com/schemas/2007/contact.cat" term="Family"/> <status>accepted</status> </entry>
The following use case describes a scenario where a user would modify a contact:
This use case begins with a request to retrieve a user's list of contacts. Each <entry> tag in the API response encapsulates information about a single contact. To update or delete a contact, send an API request to the edit URL for that contact entry.
Your application displays the list of contacts as well as a select menu next to each contact allowing the user to recategorize the contact as family or as a friend. Your application also lets users accept or reject contacts that have a status of either pending or requested.
The user modifies one or more contacts and submits his changes.
Your application loops through the contacts and sends an HTTP PUT request to update each modified contact. Your application would submit each API request to the edit URL for the contact being updated.
The following sample API request demonstrates how to delete a contact.
DELETE /feeds/api/users/USER_ID/contacts/CONTACT_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" GData-Version: 2 X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
The following list describes a common use case for deleting a contact:
As with the use case for modifying a contact, this use case begins with a request to retrieve a user's list of contacts.
Your application displays the list of contacts as well as a checkbox next to each contact allowing the user to delete that contact.
The user checks one or more contacts and submits his changes.
Your application loops through the contacts and sends an HTTP DELETE request to delete each selected contact. Your application would send each API request to the edit URL for the corresponding contact.
|
