向后兼容准则

每个 YouTube 数据 API 请求都可以指定 YouTube 处理该请求时应当使用的 API 版本。如果某一请求未指定 API 版本，那么 YouTube 将会使用系统支持的最低 API 版本处理该请求。目前，支持的最早版本是 1。请注意 API 版本号的以下特征：

YouTube 可能会发布针对特定 API 版本（尚未为其指定新的版本号）的更新。这些向后兼容的更新会包含可选的 API 功能和/或错误修正程序。
API 版本号的增加表明推出了新版本，其中所包含的更改与先前的 API 版本不兼容。

本文档定义了更新到特定 API 版本的向后兼容准则，即上文所列的第一条。这些准则旨在区分以下两种类型的 API 功能：

这些准则指出了即使您没有修改 API 版本（应当用于处理您的 API 请求）也可能更改的 API 功能。您的代码应在不中断的情况下处理这些更改。例如，如果 YouTube 在 API 响应中添加了新的 XML 标记，您的代码应忽略这些标记。
这些准则还定义了在更新特定 API 版本时 YouTube 不希望更改的 API 功能。也就是说，只有在 YouTube 发布新的 API 版本，并且此类更改不会影响您的代码时，YouTube 才会更改这些功能。

关于本文档

本文档包含以下几个部分：

API 请求部分定义了与 HTTP 请求标头、API 请求参数、API 请求中的 XML 元素名称和格式不正确的 API 请求相关的向后兼容准则。
API 响应部分定义了与 API 响应中的 XML 元素名称相关的向后兼容准则以及 XML 标记和属性在 API 响应中的显示顺序。
最佳做法部分概述了将 YouTube API 与您的客户端应用程序进行集成的建议。

API 请求

不希望更改的功能

现有的请求参数。
具有枚举值的参数的现有参数值或这些参数值的含义。
在 API POST（插入）或 PUT（更新）请求中使用的 XML 元素名称。
每一种 API 请求都需要的一系列 HTTP 请求标头。这些准则说明了 YouTube 不希望添加必需的 HTTP 请求标头，也不希望将现有的可选请求标头更改成必需的请求标头。
忽略 API 请求中不支持的参数（除非请求使用了 strict 参数，因为该参数向 YouTube 表明应拒绝包含无效请求参数的 API 请求）。

可以更改的功能

YouTube 可添加可选的请求参数。
YouTube 可为具有枚举值集合的现有参数添加新值。
YouTube 可拒绝有效参数包含无效参数值的任何请求。这样，对于因解析标准不够严格而获得通过的格式不正确的请求，在解析逻辑更正后会遭到拒绝。
YouTube 可添加可选的 HTTP 请求标头。
YouTube 在插入或更新某一资源时可能会更改其保留（存储）的信息。但是，选择更改不会影响也不必更改相应 API 请求的语法。
YouTube 可能会更改可浏览的类别组或新上传的视频指定加入的类别组。
我们随时会删除或更改未记录的功能。

API 响应

不希望更改的功能

现有的 XML 标记名称。
根据 Media RSS 规范，确定在此规范中定义且在供稿条目中多次出现的元素的顺序。例如，如果某条目包含多个 <media:thumbnail> 标记，则这些标记按重要性排序。
<category> 标记的 term 属性值，可确定供稿或供稿条目中所描述项的类型。在 <feed> 或 <entry> 标记中，<id> 标记用于指定相应条目所确定的唯一资源，而 <category> 标记则用于确定该条目所描述资源的类型。在这个 <category> 标记中，scheme 属性的值为 http://schemas.google.com/g/2005#kind，term 属性的值表明供稿条目描述的是视频、播放列表链接、订阅、联系人还是其他实体类型。

可以更改的功能

YouTube 可在 API 响应中添加新的 XML 标记。
YouTube 可在现有的 XML 标记中添加新的属性。
现有的 API 标记可以与不同值重复使用。例如，YouTube 可以添加带有另一个 type 值的新标记 <media:restriction>，也可以添加带有另一个 scheme 和另一个 role 的新标记 <media:credit>。
在 API 响应中，XML 标记和属性的顺序可能会更改。
可选的子标记可以从 API 响应中删除。
我们随时会删除或更改未记录的功能。

最佳做法

使用 <id> 标记值确定条目。
使用 self 链接检索条目。
使用 edit 链接修改或更新条目。
使用视频条目的标记值 <yt:videoid>，获得 YouTube 用于唯一标识该视频的值。请勿解析链接中的视频 ID。
使用 <link>、<content> 和 <gd:feedLink> 标记中标识的网址浏览各个供稿。YouTube 支持有限的一组网址，您可以用可靠方式构建这些网址检索特定供稿。除了下文列出的供稿网址以外，您不得创建自己的供稿网址，因为这些网址可能意外中断。
- /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（有关更多信息，请参见参考指南）
使用视频条目的标记值 <yt:videoid>，获得 YouTube 用于唯一标识该视频的值。请勿解析链接中的视频 ID。
在 API 响应中，请勿尝试解析网址中的数字或字母数字标识符。API 响应向链接到 YouTube 网站资源的标识符添加了特定标记，如视频 ID (<yt:videoid>) 及用户名（<name> 和 <media:credit>).）。
如果您提交的 API 请求用于插入 (POST) 或更新 (PUT) 信息，请对该请求使用 XML 响应，确定请求中的哪些标记值实际上由 YouTube 存储。如 API 请求的向后兼容准则中所述，YouTube 可能会在插入或更新资源时更改其保留（存储）的信息，这意味着请求中的一些标记会被忽略。
当您检索 XML 供稿时，如果您的应用程序可以让用户更新供稿条目，请存储尚未识别的 XML 标记以及与该条目相关的属性。如果用户更新了资源，您的应用程序应在更新请求中添加所有尚未识别的标记和属性。这种做法确保了您的应用程序不会在更新资源的过程中不慎删除新 API 功能的相关信息。

以下示例说明了这种最佳做法：
1. 您的应用程序可以让用户更新视频说明。
2. 您的应用程序使用 API 检索视频条目，但未能识别此条目中的一个标记。
3. 用户修改了此视频说明。
4. 您的应用程序需要将完整的视频条目发送回 API。此条目必须包含第 2 步中的未识别标记，否则相应的值可能会删除。
请先确定标记存在并且包含非零值，然后再尝试显示标记值。
如上所述，YouTube 可对具有枚举值集合的现有标记或属性添加新的值。通常，您的代码应解析具有枚举值集合的 XML 元素的值，再定义这些值的相应操作。即使该元素只有一个可用的枚举值，也推荐采用这种做法。

例如，<media:credit> 标记标识了视频的拥有者。此标记的 role 属性只有一个记录值 uploader，这说明视频是由 YouTube 合作伙伴上传的。根据这种最佳做法，您的应用程序应先确定此标记 role 属性的值确实是 uploader，然后再将相应用户标识为视频拥有者。（此规定可确保您的代码在 YouTube 添加原创作者等其他参与者类型时不会错误标识视频拥有者。）
- 如果某标记具有枚举值集合而您无法识别该标记的值，则您应忽略此标记所对应的整个 <entry>。
- 对于 scheme 属性的值为 http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat 的 <category> 标记，如果您无法识别其中 term 属性的值，请忽略相应的订阅供稿条目。这个特殊标记用于标识该条目所标识的订阅类型。如果您的应用程序无法识别订阅类型，则不应显示有关该条目的信息。
- 如果任何其他的属性具有枚举值集合而您无法识别该属性的值，您应当忽略该属性所对应的标记。
您的应用程序代码应时刻注意 yt:error 讯息。如果 API 操作失败，则您的应用程序应识别出错误并向用户显示实用的讯息。
YouTube 可随时添加用于视频分类的新类别。YouTube 也可以更新或弃用已有的类别。您可以在 http://gdata.youtube.com/schemas/2007/categories.cat 上检索关于当前类别的文件。
- 如果您的应用程序可以让用户按类别浏览视频或上传视频，请每星期检索更新的类别文件。
- 如果您的应用程序可以让用户按类别浏览视频，则在 API 响应类别搜索时返回空供稿的情况下，请同样检索更新的类别文件。
- 如果您的应用程序可以让用户上传视频，请同样在上传视频前检索更新的类别文件，并确认与上传视频相关联的类别仍是可分配的。有关更多信息，请参见参考指南。（请注意，如果您尝试将视频分配给不可分配的类别，则 API 会返回一条错误讯息，其 <code> 标记的值为 deprecated。）
使用 API 响应中的 <link> 标记识别供稿条目上一页和/或下一页的分页链接。有关更多信息，请参见参考指南中的对结果进行分页部分。