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

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

  • YouTube может выпускать обновления для определенной версии API, для которой выпуску не присвоен новый номер версии. Эти обратно совместимые обновления могут включать дополнительные функции 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.

  • В разделе «Рекомендации» приводятся рекомендации по интеграции API YouTube с вашим клиентским приложением.

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> значение атрибута схемы равно 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 , чтобы отредактировать или обновить запись.

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

  • Используйте 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/favourites
    • /feeds/api/users/default/contacts
    • /feeds/api/users/default/inbox
    • /feeds/api/users/default/плейлисты
    • /feeds/api/users/default/subscriptions
    • /feeds/api/users/default/newsubscriptionvideos
    • /feeds/api/standardfeeds/ regionID / feedID _CATEGORY_NAME (дополнительную информацию см. в справочном руководстве )

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

    • Игнорируйте запись фида подписок, если вы не распознаете значение атрибута 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, чтобы определить ссылки на страницы для предыдущей и/или следующей страницы записей в канале. Дополнительную информацию см. в разделе « Пролистывание результатов» справочного руководства.