Developer's Guide: Data API Protocol – Video Responses

A video response is a video that is associated, as a reply, with a second video. A video can be designated as a video response with exactly one other video. Logged-in users can add or delete video responses, but the user must have uploaded the video that is being added or deleted.

This page contains the following sections:

Retrieving a list of video responses

This section explains how to retrieve a feed of video responses for a video. Note that some videos may not have any video responses.

Each video entry in an API response contains a series of <link> tags. The <link> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007/#video.responses identifies the URL for retrieving video responses for that video entry. (The <link> tag's href attribute identifies the URL.)

<link rel="http://gdata.youtube.com/schemas/2007#video.responses"
     type="application/atom+xml"
     href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses"/>

The API response for this query has exactly the same format as the sample response in the Understanding video feeds and entries section of this document.

Adding a video response

To add a video response, you will submit an HTTP POST request that identifies two videos – the video that to which you are adding the video response and the video that is being added as a response.

The following XML illustrates the format for a sample request for adding a video response. In the request, the string ORIGINAL_VIDEO_ID identifies the video that to which you are adding the video response, and the string RESPONSE_VIDEO_ID identifies the video that is being added as a response.

POST /feeds/api/videos/ORIGINAL_VIDEO_ID/responses 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">
  <id>RESPONSE_VIDEO_ID</id>
</entry>

If YouTube successfully handles your request, the API will return a 201 HTTP response code. However, the video response will not be listed in the video responses feed until the response has been approved by the owner of the original video.

Typically, a user will add a video response to a video after watching that video. In some cases, the user will select a video that he has already uploaded as the response. In other cases, the user will upload a new video, which will serve as the video response. The following list identifies the API calls associated with each type of API request:

• The user selects an existing video to serve as a video response.

  1. You retrieve information about a video by submitting an API request to that video's self URL.

  2. The user clicks a link to add a video response to the video and elects to respond with a previously uploaded video. You extract the video response URL for the video to which the user is adding the response.

  3. You send an API request to retrieve the list of videos uploaded by the user. You display the list of videos so that the user can select one of the videos.

  4. When the user selects a video, you send an HTTP POST request to the video response URL for the original video that specifies the <yt:videoid> of the selected video. The Retrieving a list of video responses section explains how to identify the video response URL for a feed entry.

• The user uploads a new video, which will serve as the video response.

  1. This use case also begins with an API request to retrieve information about a video.

  2. The user clicks a link to add a video response to the video and elects to upload (or capture) a new video. You extract the video response URL for the video to which the user is adding the response.

  3. You send an API request to upload the new video to YouTube's video library. If the user first needs to capture the video, you may also need to present a form that lets the user enter a title and other information about the video.

  4. You extract the video ID for the newly added video from the API response to your upload request.

  5. You send an HTTP POST request to the video response URL for the original video to add the newly added video as a video response.

Deleting a video response

To delete a video response, submit an HTTP DELETE request that identifies the two videos, as shown in the following example.

DELETE /feeds/api/videos/VIDEO_ID/responses/VIDEO_RESPONSE_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