Google is committed to advancing racial equity for Black communities. See how.

Руководство по обратной совместимости

В запросах API может указываться версия API, которая должна использоваться YouTube для обработки запроса. Если в запросе не указана версия API, YouTube будет использовать для обработки запроса самую раннюю поддерживаемую версию. В настоящий момент такой версией является 1. Обратите внимание на следующие особенности номеров версий API.

  • YouTube может выпустить обновление для конкретной версии API без присвоения нового номера версии. Такие обновления с обратной совместимостью могут включать дополнительные функции API или исправления ошибок, или то и другое.

  • Увеличение номера версии API указывает на то, что данная версия содержит изменения, которые несовместимы с предыдущими версиями.

В этом документе приводится руководство по обратной совместимости при обновлении с переходом к определенной версии API, для указания которой выше служит первый элемент. В руководстве устанавливаются различия между следующими типами функциональности API.

  • В руководстве указывается функциональность API, которая может измениться, даже если не изменяется версия API, используемая для обработки запросов API. Эти изменения должны обрабатываться вашим кодом без нарушений в работе. Например, если YouTube добавляет новые XML-теги в ответы API, код должен игнорировать эти теги.

  • В руководстве также определяется функциональность API, которую YouTube не планирует изменять при обновлении определенной версии API. Другими словами, данная функциональность может измениться только при выпуске YouTube новой версии API, так что ваш код не должен пытаться обрабатывать данные типы изменений.

Об этом документе

Данный документ состоит из следующих разделов.

  • В разделе Запросы API представлено руководство по обратной совместимости для заголовков HTTP-запросов, параметров запросов API, имен XML-элементов (которые появляются в запросах API) и неправильно сформированных запросов API.

  • В разделе Ответы API представлено руководство по обратной совместимости для имен XML-элементов (которые используются в ответах API) и порядок, в котором теги и атрибуты XML появляются в ответах API.

  • В разделе Оптимальные методы приводятся рекомендации по интеграции YouTube API с клиентскими приложениями.

Запросы API

Функциональные возможности, изменение которых не планируется

  • Имеющиеся параметры запросов.

  • Имеющиеся значения параметров для параметров с перечисляемыми значениями и смысл этих значений.

  • Имена XML-элементов, используемых в запросах API POST (вставить) и PUT (обновить).

  • Набор заголовков HTTP-запросов, требуемых для каждого типа запросов API. Эта рекомендация означает, что YouTube не планирует добавлять обязательные заголовки HTTP-запросов или изменять существующие необязательные заголовки на обязательные.

  • Поведение, при котором в запросах API игнорируются неподдерживаемые параметры, за исключением использования в запросе параметра strict, который предписывает YouTube отклонить запрос API, содержащий недействительные параметры запроса.

Функциональные возможности, которые могут быть изменены

  • YouTube может добавить необязательные параметры запросов.

  • YouTube может добавить новые значения для существующих параметров с перечисляемым набором значений.

  • YouTube может отклонить запрос, в котором действительные параметры имеют недействительные значения. В результате неправильно сформированные запросы, которые были приняты по причине слишком нестрогого синтаксического анализа, могут быть отклонены при исправлении логики синтаксического анализа.

  • YouTube может добавить необязательные заголовки HTTP-запросов.

  • YouTube может изменить сведения, которые он сохраняет при вставке или обновлении ресурса. Но такое решение не затрагивает или не требует изменений в синтаксисе соответствующих запросов API.

  • YouTube может изменить набор просматриваемых категорий или набор категорий, которым можно назначить вновь загруженное видео.

  • Недокументированные функциональные возможности могут быть в любое время исключены или изменены.

Ответы API

Функциональные возможности, изменение которых не планируется

  • Имеющиеся имена XML-тегов.

  • Соблюдение спецификации Media RSS для определения порядка элементов, которые определены в этой спецификации и появляются несколько раз в записи фида. Например, если запись содержит несколько тегов <media:thumbnail>, они упорядочиваются по значимости.

  • Значение атрибута term тега <category>, которое указывает тип элемента, описанного в фиде или записи фида. Применяемые в теге <feed> или <entry> тег <id> задает уникальный ресурс, определенный этой записью, а тег <category> определяет тип ресурса, описанного записью. В этом теге <category> атрибут "scheme" имеет значение http://schemas.google.com/g/2005#kind, а значение атрибута "term" указывает, что описывают записи фида – видео, ссылки на плейлисты, подписки, контакты или объекты других типов.

Функциональные возможности, которые могут быть изменены

  • YouTube может добавить новые XML-теги в ответы API.

  • YouTube может добавить новые атрибуты в имеющиеся XML-теги.

  • Существующие теги API могут повторяться с различными значениями. Например, YouTube может добавить новый тег <media:restriction> с другим значением type или новый тег <media:credit> с другими scheme и role.

  • Порядок XML-тегов и атрибутов в ответе API может изменяться.

  • Необязательные дочерние теги могут быть удалены из ответов API.

  • Недокументированные функциональные возможности могут быть в любое время исключены или изменены.

Оптимальные методы

  • Используйте значение тега <id> для определения записи.

  • Используйте ссылку self для получения записи.

  • Используйте ссылку edit для редактирования или обновления записи.

  • Чтобы получить значение, которое YouTube использует для однозначного определения видео, используйте значение тега <yt:videoid> для этой записи о видео. Не выполняйте синтаксический анализ идентификатора видео из ссылки.

  • Используйте URL, указанный в тегах <link>, <content> и <gd:feedLink>, для переходов между фидами. YouTube поддерживает ограниченный набор URL, которые можно формировать для получения определенных фидов, будучи уверенным в их полной надежности. Кроме перечисленных ниже URL, не следует создавать свои собственные URL фидов, поскольку они могут неожиданно перестать работать.

    • /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 (дополнительные сведения см. в справочном руководстве)
  • Для получения значения, используемого YouTube для идентификации видео, используется значение тега <yt:videoid> для этой записи о видео. Не выполняйте синтаксический анализ идентификатора видео из ссылки.

  • Не выполняйте синтаксический анализ числовых или символьных идентификаторов в URL ответов API. Ответы API содержат определенные теги для идентификаторов, которые связываются с ресурсами на веб-сайте YouTube, такие как идентификаторы видео (<yt:videoid>) и именa пользователей (<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>, внутри которого появляется этот тег.

    • Проигнорируйте запись фида подписки, если не удается распознать значение атрибута term тега <category>, атрибут scheme которого имеет значение http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Этот тег определяет тип подписки, задаваемой данной записью. Если приложение не распознает тип подписки, оно не должно отображать сведения об этой записи.

    • Если какой-либо другой атрибут имеет перечисляемый набор значений и значение этого атрибута не распознается, следует проигнорировать тег, в котором появляется этот атрибут.

  • Код вашего приложения должен ожидать поступления сообщения yt:error в любое время. Если операцию API не удается выполнить, приложение должно определить ошибку и вывести на экран сообщение для пользователя.

  • YouTube может в любое время добавить новые категории для классификации видео. YouTube может также обновить или исключить существующие категории. Вы можете получить текущий файл категорий по адресу http://gdata.youtube.com/schemas/2007/categories.cat.

    • Если ваше приложение позволяет пользователям просматривать видео по категориям или загружать видео, следует получать обновленный файл категорий еженедельно.

    • Если ваше приложение позволяет пользователям просматривать видео по категориям, обновленный файл категорий следует получать также в том случае, если API возвращает пустой фид в ответ на поиск категории.

    • Если ваше приложение позволяет пользователям добавлять видео, следует получать обновленный файл категорий перед добавлением видео и проверять, что категория, назначенная добавляемому видео, все еще может применяться. Подробные сведения см. в справочном руководстве. (Обратите внимание, что при попытке назначить видео несуществующую категорию API возвратит сообщение об ошибке, для которого тег <code> принимает значение deprecated.)

  • Используйте теги <link> в ответе API для указания ссылок на предыдущую и/или следующую страницу записей в фиде. Дополнительные сведения см. в разделе Переход по страницам результатов справочного руководства.