Developer's Guide: Data API Protocol – Audience

Note: This page may discuss features that aren't among those that you selected in the documentation adviser. Even though you don't want to implement those features now, we still don't want you to forget about them.

To bookmark these settings or send a link to this customized version of these documents, copy (right-click) the link labeled "link" below the Customized! header in the left navigation menu.

The YouTube Data API allows applications to perform functions normally executed on the YouTube website. The API enables your application to search for YouTube videos and to retrieve standard video feeds, comments and video responses. In addition, the API lets your application upload videos to YouTube or update existing videos. Your application can also retrieve playlists, subscriptions, user profiles and more. Finally, your application can submit authenticated requests to enable users to create playlists, subscriptions, contacts and other account-specific entities.

Audience

This documentation is intended for programmers who are writing client applications that interact with YouTube. It provides examples of basic API operations using raw HTTP and XML. Java , .NET, PHP and Python developers may prefer to read the language-specific developer guides that explain how to use the client libraries for those languages to perform similar functions.

This documentation assumes that you understand the general principles behind the Google Data APIs protocol. Google Data APIs provide a simple, standard protocol for reading and writing data on the web. Google Data APIs are based on the Atom 1.0 and RSS 2.0 syndication formats as well as the Atom Publishing Protocol.

About this documentation

This documentation is divided into the following sections:

• The Authentication section describes the two different authentication methods available for associating API operations with a specific user account. This section also outlines the differences between authentication for the YouTube Data API and other Google Data APIs. Throughout this documentation, explanations of specific API functions will clearly indicate whether the function requires user authentication.

• The Understanding video feeds and entries section provides a sample API response and explains how to extract information about a single video from a list of videos or a set of search results. This section also illustrates how the XML elements in a YouTube Data API response correspond to the video information typically displayed on YouTube's website. This section also explains the API request format for updating an individual video entry.

• The Retrieving and Searching for Videos section explains how to fetch a list of videos. The YouTube Data API defines several types of standard feeds, such as top-rated or most-viewed videos. This section also explains how also to retrieve a list of videos uploaded by a specific user or a list of related videos, which are videos that YouTube has determined are similar to a particular video. Finally, this section explains how to use the API to let users search through YouTube's video library for videos matching specific search terms or categories.

• The Uploading videos section briefly explains two ways that you can allow users to upload videos to YouTube from your application. This section also presents process flow diagrams for each upload method and explains how those methods work in conjunction with the authentication scheme that you are using.

  You may need to let users upload videos to use certain other API functions. For example, the API provides a function for adding a video response to a video. However, if the user is uploading a new video as a video response, then your client will need to follow the video uploading instructions to add the video to YouTube before identifying the new video as a response to an existing video.

• The Updating and deleting videos section explains how to enable a user to update or delete his videos.

• The Using Community Features section describes API functions that allow your users to interact with YouTube videos. These functions explain requests for posting a rating, comment, video response or complaint to an existing video. You can also use the API to retrieve lists of video comments or video responses or to delete a video response.

• The Saving and Collecting Videos section explains how to use the API to access, create and update favorite videos, video playlists and subscriptions to YouTube channels.

• The Enabling User Interaction section explains how to use the API to retrieve and update user profiles. This section also explains how to retrieve, add, update and delete user contacts.

API versioning

API requests can specify the version of the API that YouTube should use to handle the request. Your request can specify an API version using either the v parameter or the GData-Version HTTP request header. If a request does not specify an API version, then YouTube will use the oldest supported version of the API to handle that request. The oldest supported version is currently 1.

Note: All of the sample requests in this documentation use the GData-Version HTTP request header.

Please note the following characteristics of API version numbers:

• YouTube may release updates to a specific API version for which the release is not assigned a new version number. These backward-compatible updates can include optional API features, bug fixes or both.

• An increment of the API version number identifies a release that contains changes that are incompatible with previous API versions.

For more information, see the Backward Compatibility Guidelines, which identify API behaviors that may change even if you do not modify the API version that should be used to handle your API requests. The guidelines also define API behaviors that YouTube does not intend to change for a particular API version.