Backward Compatibility Guidelines

Each YouTube Data API request can specify the version of the API that YouTube should use to handle that request. 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. 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.

This document defines backward-compatibility guidelines for updates to a specific API version, the first item listed above. The guidelines seek to distinguish between the following types of API functionality:

• The guidelines identify API functionality that may change even if you do not modify the API version that should be used to handle your API requests. Your code should handle these changes without breaking. For example, if YouTube adds new XML tags to API responses, then your code should ignore those tags.

• The guidelines also define API functionality that YouTube does not intend to change when updating a specific API version. In other words, you should only expect that functionality to change if YouTube releases a new API version, and your code need not attempt to handle these types of changes.

About this document

This document contains the following sections:

• The API requests section defines backward-compatibility guidelines related to HTTP request headers, API request parameters, XML element names (as they appear in API requests) and improperly formed API requests.

• The API responses section defines backward-compatibility guidelines related to XML element names (as they appear in API responses) and the order in which XML tags and attributes appear in API responses.

• The Best practices section outlines recommendations for integrating the YouTube API with your client application.

API requests

Functionality that is not intended to change

• Existing request parameters.

• Existing parameter values for parameters that have enumerated values or the meanings of those parameter values.

• The names of XML elements used in API POST (insert) or PUT (update) requests.

• The set of HTTP request headers that are required for each type of API request. This guideline means that YouTube does not intend to add required HTTP request headers or to change existing optional request headers to be required.

• The behavior of ignoring unsupported parameters in an API request unless the request uses the strict parameter, which instructs YouTube to reject an API request that contains invalid request parameters.

Functionality that may change

• YouTube may add optional request parameters.

• YouTube may add new values for existing parameters that have enumerated sets of values.

• YouTube can reject any request in which valid parameters contain invalid parameter values. As a result, improperly formed requests that have been accepted due to overly lenient parsing may be rejected if the parsing logic is corrected.

• YouTube may add optional HTTP request headers.

• YouTube may change the information that it retains (stores) when inserting or updating a resource. However, such a decision would not affect or require changes to the syntax of the corresponding API requests.

• YouTube may change the set of browseable categories or the set of categories that newly uploaded videos can be assigned to.

• Undocumented functionality may be removed or changed at any time.

API responses

Functionality that is not intended to change

• Existing XML tag names.

• Following the Media RSS specification to determine the order of elements that are defined in that specification and that appear multiple times in a feed entry. For example, if an entry contains multiple <media:thumbnail> tags, they are ordered by importance.

• The term attribute value of the <category> tag that identifies the type of item described in a feed or feed entry. Within the <feed> or <entry> tag, the <id> tag specifies the unique resource identified by the entry, and a <category> tag identifies the kind of resource described by the entry. For this <category> tag, the value of the scheme attribute is http://schemas.google.com/g/2005#kind and the value of the term attribute indicates whether feed entries describe videos, playlist links, subscriptions, contacts or another entity type.

Functionality that may change

• YouTube may add new XML tags to API responses.

• YouTube may add new attributes to existing XML tags.

• Existing API tags may be repeated with different values. For example, YouTube could add a new <media:restriction> tag with a different type value or a new <media:credit> tag with a different scheme and role.

• The order of XML tags and attributes in the API response may change.

• Optional child tags may be removed from API responses.

• Undocumented functionality may be removed or changed at any time.

Best practices

• Use the <id> tag value to identify an entry.

• Use the self link to retrieve an entry.

• Use the edit link to edit or update an entry.

• Use the <yt:videoid> tag value for a video entry to obtain the value that YouTube uses to uniquely identify that video. Do not parse the video ID from a link.

• Use the URLs identified in <link>, <content> and <gd:feedLink> tags to navigate between feeds. YouTube supports a limited set of URLs that you can reliably construct to retrieve specific feeds. Aside from those feed URLs, which are listed below, you should not construct your own feed URLs since they may unexpectedly stop working.

  • /feeds/api/videos/<videoid>
  • /feeds/api/users/default
  • /feeds/api/users/default/uploads
  • /feeds/api/users/default/favorites
  • /feeds/api/users/default/contacts
  • /feeds/api/users/default/inbox
  • /feeds/api/users/default/playlists
  • /feeds/api/users/default/subscriptions
  • /feeds/api/users/default/newsubscriptionvideos
  • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (see the reference guide for more information)

• Do not try to parse numeric or alphanumeric identifies from URLs in an API response. API responses include specific tags for identifiers that link to resources on the YouTube website, such as video IDs (<yt:videoid>) and usernames (<name> and <media:credit>).

• If you submit an API request to insert (POST) or update (PUT) information, use the XML response to that request to determine which tag values in the request were actually stored by YouTube. As noted in the backward-compatibility guidelines for API requests, YouTube may change the information that it retains (stores) when inserting or updating a resource, meaning that some of the tags in the request may be ignored.

• When you retrieve an XML feed, store unrecognized XML tags and attributes related to a feed entry if your application enables the user to update that entry. If the user updates the resource, your application should include any unrecognized tags and attributes in the update request. This practice ensures that your application does not inadvertently delete information related to new API features in the process of updating a resource.

  The following example illustrates this best practice:

  1. Your application enables a user to update a video description.
  2. Your application retrieves the video entry using the API but does not recognize one of the tags in the entry.
  3. The user modifies the video description.
  4. Your application needs to send a complete video entry back to the API. The entry needs to include the unrecognized tag from step 2; otherwise, that value might be deleted.

• Confirm that a tag exists and contains a non-null value before trying to display the tag value.

• As noted above, YouTube may add new values for existing tags or attributes that have enumerated sets of values. As a rule, your code should parse the values of XML elements that have enumerated sets of values and then define actions appropriate to those values. This practice is recommended even if only one possible value is enumerated for the element.

  For example, the <media:credit> tag identifies the owner of a video. The only documented value for the tag's role attribute is uploader, which indicates that the video was uploaded by a YouTube partner. This best practice stipulates that your application should confirm that the value of the tag's role attribute is indeed uploader before identifying the corresponding user as the video owner. (This precaution ensures that your code doesn't inaccurately identify a video owner if YouTube adds other types of credits – e.g. director – for a video.)

  • If a tag has an enumerated set of values and you do not recognize the value of that tag, you should ignore the entire <entry> within which that tag appears.

  • Ignore a subscriptions feed entry if you do not recognize the value of the term attribute for the <category> tag that has a scheme attribute value of http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. That particular tag identifies the type of subscription identified by the entry. If your application does not recognize the subscription type, it should not display information about that entry.

  • If any other attribute has an enumerated set of values and you do not recognize the value of that attribute, you should ignore the tag in which the attribute appears.

• Your application code should expect a yt:error message at any time. In the event that an API operation fails, your application should identify the error and display a meaningful message to the user.

• YouTube may add new categories for classifying videos at any time. YouTube may also update or deprecate existing categories. You can retrieve a current categories file from http://gdata.youtube.com/schemas/2007/categories.cat.

  • If your application enables users to browse videos by category or upload videos, retrieve an updated categories file on a weekly basis.

  • If your application enables users to browse videos by category, also retrieve an updated categories file if the API returns an empty feed in response to a category search.

  • If your application enables users to upload videos, also retrieve an updated categories file before uploading a video and confirm that the category associated with the uploaded video is still assignable. See the reference guide for more information. (Note that if you try to assign a video to a non-assignable category, the API will return an error message for which the value of the <code> tag is deprecated.)

• Use the <link> tags in an API response to identify pagination links for the previous and/or next page of entries in a feed. See the Paging through results section of the reference guide for more information.