下位互換性に関するガイドライン

各 YouTube Data API リクエストで、そのリクエストの処理に使用する API のバージョンを指定できます。リクエストで API バージョンが指定されていない場合、YouTube はサポートされている最も古いバージョンの API を使用してリクエストを処理します。現在サポートされている最も古いバージョンは 1 です。API バージョン番号には次の特性があります。

  • YouTube は、リリースに新しいバージョン番号が割り当てられていない特定の API バージョンのアップデートをリリースすることがあります。これらの下位互換性のあるアップデートには、オプションの API 機能、バグ修正、またはその両方が含まれる場合があります。

  • API バージョン番号がインクリメントされたリリースには、以前の API バージョンと互換性のない変更が含まれています。

このドキュメントでは、特定の API バージョン（上記の最初の項目）のアップデートに関する下位互換性ガイドラインを定義します。このガイドラインでは、次のタイプの API 機能を区別しています。

  • このガイドラインでは、API リクエストの処理に使用する API バージョンを変更しなくても変更される可能性がある API 機能を特定します。コードは、このような変更を破綻させることなく処理する必要があります。たとえば、YouTube が API レスポンスに新しい XML タグを追加した場合、コードではこれらのタグを無視する必要があります。

  • また、特定の API バージョンの更新時に YouTube が変更する予定のない API 機能も定義されています。つまり、この機能が変更されるのは、YouTube が新しい API バージョンをリリースした場合のみであり、コードでこのような変更を処理する必要はありません。

このドキュメントについて

このドキュメントでは以下の項目について説明します。

  • API リクエストのセクションでは、HTTP リクエスト ヘッダー、API リクエスト パラメータ、XML 要素名（API リクエストに表示される形式）、不適切に形成された API リクエストに関連する下位互換性ガイドラインを定義します。

  • [API レスポンス] セクションでは、XML 要素名（API レスポンスに表示される名前）と、XML タグと属性が API レスポンスに表示される順序に関連する下位互換性ガイドラインを定義します。

  • ベスト プラクティスのセクションでは、YouTube API をクライアント アプリケーションと統合するための推奨事項について説明します。

API リクエスト

変更を意図していない機能

  • 既存のリクエスト パラメータ。

  • 列挙値を持つパラメータの既存のパラメータ値、またはそれらのパラメータ値の意味。

  • API POST（挿入）リクエストまたは PUT（更新）リクエストで使用される XML 要素の名前。

  • API リクエストの種類ごとに必要な HTTP リクエスト ヘッダーのセット。このガイドラインは、YouTube が必須の HTTP リクエスト ヘッダーを追加したり、既存のオプションのリクエスト ヘッダーを必須に変更したりする意図がないことを意味します。

  • リクエストで strict パラメータが使用されていない限り、API リクエストでサポートされていないパラメータを無視する動作。このパラメータは、無効なリクエスト パラメータを含む API リクエストを拒否するよう YouTube に指示します。

変更される可能性のある機能

  • YouTube は、オプションのリクエスト パラメータを追加する場合があります。

  • 値の列挙セットを持つ既存のパラメータに新しい値が追加される場合があります。

  • 有効なパラメータに無効なパラメータ値が含まれているリクエストは、YouTube によって拒否される場合があります。そのため、過度に緩い解析により承認された不適切な形式のリクエストは、解析ロジックが修正されると拒否される可能性があります。

  • YouTube は、オプションの HTTP リクエスト ヘッダーを追加する場合があります。

  • YouTube は、リソースの挿入または更新時に保持（保存）する情報を変更することがあります。ただし、このような決定は、対応する API リクエストの構文に影響したり、変更を必要としたりしません。

  • 閲覧可能なカテゴリや、新しくアップロードした動画に割り当てることができるカテゴリは、変更される場合があります。

  • ドキュメントに記載されていない機能は、いつでも削除または変更される可能性があります。

API レスポンス

変更を意図していない機能

  • 既存の XML タグ名。

  • Media RSS 仕様に従って、その仕様で定義され、フィード エントリに複数回表示される要素の順序を決定します。たとえば、エントリに複数の <media:thumbnail> タグが含まれている場合、それらは重要度順に並べ替えられます。

  • フィードまたはフィード エントリで記述されているアイテムのタイプを識別する <category> タグの term 属性値。<feed> タグまたは <entry> タグ内で、<id> タグはエントリによって識別される一意のリソースを指定し、<category> タグはエントリで記述されているリソースの種類を識別します。この <category> タグでは、スキーム属性の値は http://schemas.google.com/g/2005#kind で、ターム属性の値は、フィード エントリが動画、再生リストのリンク、チャンネル登録、連絡先、または他のエンティティ タイプを表すかどうかを示します。

変更される可能性のある機能

  • 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> タグで指定した URL を使用して、フィードを移動します。YouTube では、特定のフィードを取得するために信頼できる方法で作成できる URL のセットが限定的にサポートされています。以下に記載するフィード 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（詳細については、リファレンス ガイドをご覧ください）。

  • API レスポンスの URL から数値または英数字の ID を解析しようとしないでください。API レスポンスには、YouTube ウェブサイトのリソースにリンクする ID の特定のタグが含まれます。たとえば、動画 ID（<yt:videoid>）やユーザー名（<name>、<media:credit>).）などです。

  • 情報を挿入（POST）または更新（PUT）する API リクエストを送信する場合は、そのリクエストに対する XML レスポンスを使用して、リクエスト内のどのタグ値が YouTube によって実際に保存されたかを判断します。API リクエストの下位互換性ガイドラインに記載されているように、YouTube はリソースの挿入または更新時に保持（保存）する情報を変更することがあります。つまり、リクエスト内のタグの一部が無視される可能性があります。

  • XML フィードを取得するときに、アプリでユーザーがエントリを更新できるようにする場合は、認識されない XML タグとフィード エントリに関連する属性を保存します。ユーザーがリソースを更新する場合、アプリは認識できないタグと属性を更新リクエストに含める必要があります。これにより、リソースの更新プロセスで新しい API 機能に関連する情報が誤って削除されることがなくなります。

    次の例は、このベスト プラクティスを示しています。

    1. ユーザーが動画の説明を更新できるアプリです。
    2. アプリは API を使用して動画エントリを取得しますが、エントリ内のタグの 1 つを認識しません。
    3. ユーザーが動画の説明を変更します。
    4. アプリケーションは、完全な動画エントリを API に送り返す必要があります。エントリには、手順 2 の認識されないタグを含める必要があります。そうしないと、その値が削除される可能性があります。

  • タグ値を表示する前に、タグが存在し、null 以外の値が含まれていることを確認します。

  • 上記のように、値の列挙セットを持つ既存のタグまたは属性に新しい値が追加される場合があります。通常、コードでは、列挙型の値セットを持つ XML 要素の値を解析し、それらの値に適したアクションを定義する必要があります。この方法は、要素に指定できる値が 1 つしかない場合でも推奨されます。

    たとえば、<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 から空のフィードが返された場合、更新されたカテゴリ ファイルも取得します。

    • アプリでユーザーが動画をアップロードできるようにしている場合は、動画をアップロードする前に更新されたカテゴリ ファイルを取得し、アップロードされた動画に関連付けられたカテゴリが引き続き割り当て可能であることを確認してください。詳しくは、リファレンス ガイドをご覧ください。（動画を割り当てられないカテゴリに割り当てようとすると、<code> タグの値が deprecated のエラー メッセージが API から返されます）。

  • API レスポンスの <link> タグを使用して、フィードのエントリの前のページまたは次のページのページネーション リンクを識別します。詳細については、リファレンス ガイドの結果のページングをご覧ください。