Richtlinien zur Abwärtskompatibilität

Für jede YouTube Data API-Anfrage kann die Version der API angegeben werden, die YouTube zum Ausführen dieser Anfrage verwenden soll. Wenn für eine Anfrage keine API-Version angegeben ist, verwendet YouTube die älteste unterstützte API-Version, um die Anfrage zu verarbeiten. Die älteste unterstützte Version ist derzeit 1. Beachten Sie die folgenden Merkmale von API-Versionsnummern:

  • YouTube kann Updates für eine bestimmte API-Version veröffentlichen, für die dem Release keine neue Versionsnummer zugewiesen wird. Diese abwärtskompatiblen Updates können optionale API-Funktionen oder Fehlerkorrekturen oder beides enthalten.

  • Eine Erhöhung der API-Versionsnummer kennzeichnet einen Release, der Änderungen enthält, die mit früheren API-Versionen nicht kompatibel sind.

In diesem Dokument werden Richtlinien für die Abwärtskompatibilität für Updates einer bestimmten API-Version definiert (siehe oben). In den Richtlinien wird zwischen den folgenden Arten von API-Funktionen unterschieden:

  • In den Richtlinien werden API-Funktionen beschrieben, die sich auch dann ändern können, wenn Sie die API-Version, die für die Verarbeitung Ihrer API-Anfragen verwendet werden soll, nicht ändern. Ihr Code sollte diese Änderungen problemlos verarbeiten. Wenn YouTube beispielsweise API-Antworten neue XML-Tags hinzufügt, sollten diese Tags von deinem Code ignoriert werden.

  • Außerdem werden in den Richtlinien API-Funktionen definiert, die YouTube bei der Aktualisierung einer bestimmten API-Version nicht ändern möchte. Mit anderen Worten: Du solltest davon ausgehen, dass sich diese Funktion nur ändert, wenn YouTube eine neue API-Version veröffentlicht. Dein Code muss diese Art von Änderungen also nicht verarbeiten.

Informationen zu diesem Dokument

Diese FAQs sind in folgende Abschnitte gegliedert:

  • Im Abschnitt API-Anfragen werden Richtlinien für die Abwärtskompatibilität in Bezug auf HTTP-Anfrageheader, API-Anfrageparameter, XML-Elementnamen (wie sie in API-Anfragen erscheinen) und nicht ordnungsgemäß formatierte API-Anfragen definiert.

  • Im Abschnitt API-Antworten werden Richtlinien für die Abwärtskompatibilität in Bezug auf XML-Elementnamen (wie sie in API-Antworten erscheinen) und die Reihenfolge, in der XML-Tags und ‑Attribute in API-Antworten erscheinen, definiert.

  • Im Abschnitt Best Practices findest du Empfehlungen zur Einbindung der YouTube API in deine Clientanwendung.

API-Anfragen

Funktionen, die sich nicht ändern sollen

  • Vorhandene Anfrageparameter

  • Vorhandene Parameterwerte für Parameter mit Aufzählungswerten oder die Bedeutung dieser Parameterwerte.

  • Die Namen der XML-Elemente, die in API-POST- (Einfügen) oder PUT-Anfragen (Aktualisieren) verwendet werden.

  • Die HTTP-Anfrageheader, die für jeden API-Anfragetyp erforderlich sind. Das bedeutet, dass YouTube keine erforderlichen HTTP-Anfrage-Header hinzufügen oder vorhandene optionale Anfrage-Header in erforderliche ändern wird.

  • Das Verhalten, bei dem nicht unterstützte Parameter in einer API-Anfrage ignoriert werden, es sei denn, die Anfrage verwendet den Parameter strict, der YouTube anweist, eine API-Anfrage mit ungültigen Anfrageparametern abzulehnen.

Funktionen, die sich ändern können

  • YouTube kann optionale Anfrageparameter hinzufügen.

  • YouTube kann neue Werte für vorhandene Parameter hinzufügen, die Wertelisten enthalten.

  • YouTube kann jede Anfrage ablehnen, die gültige Parameter mit ungültigen Parameterwerten enthält. Falsch formatierte Anfragen, die aufgrund eines zu strengen Parsings akzeptiert wurden, werden möglicherweise abgelehnt, wenn die Parsinglogik korrigiert wird.

  • YouTube kann optionale HTTP-Anfrageheader hinzufügen.

  • YouTube kann die Informationen ändern, die beim Einfügen oder Aktualisieren einer Ressource gespeichert werden. Eine solche Entscheidung hätte jedoch keine Auswirkungen auf die Syntax der entsprechenden API-Anfragen und würde auch keine Änderungen erfordern.

  • YouTube kann die Kategorien, die durchsucht werden können, oder die Kategorien, denen neu hochgeladene Videos zugewiesen werden können, ändern.

  • Nicht dokumentierte Funktionen können jederzeit entfernt oder geändert werden.

API-Antworten

Funktionen, die sich nicht ändern sollen

  • Vorhandene XML-Tag-Namen

  • Die Reihenfolge der Elemente, die in der Media RSS-Spezifikation definiert sind und mehrmals in einem Feedeintrag vorkommen, wird gemäß dieser Spezifikation festgelegt. Wenn ein Eintrag beispielsweise mehrere <media:thumbnail>-Tags enthält, werden diese nach Wichtigkeit sortiert.

  • Der term-Attributwert des <category>-Tags, der den Typ des Artikels angibt, der in einem Feed oder Feedeintrag beschrieben wird. Innerhalb des <feed>- oder <entry>-Tags gibt das <id>-Tag die eindeutige Ressource an, die durch den Eintrag identifiziert wird. Ein <category>-Tag gibt die Art der Ressource an, die durch den Eintrag beschrieben wird. Für dieses <category>-Tag ist der Wert des Attributs „schema“ http://schemas.google.com/g/2005#kind. Der Wert des Attributs „term“ gibt an, ob Feedeinträge Videos, Playlist-Links, Abos, Kontakte oder einen anderen Entitätstyp beschreiben.

Funktionen, die sich ändern können

  • YouTube kann API-Antworten neue XML-Tags hinzufügen.

  • YouTube kann vorhandenen XML-Tags neue Attribute hinzufügen.

  • Vorhandene API-Tags können mit unterschiedlichen Werten wiederholt werden. YouTube kann beispielsweise ein neues <media:restriction>-Tag mit einem anderen type-Wert oder ein neues <media:credit>-Tag mit anderen scheme- und role-Werten hinzufügen.

  • Die Reihenfolge der XML-Tags und ‑Attribute in der API-Antwort kann sich ändern.

  • Optionale untergeordnete Tags können aus API-Antworten entfernt werden.

  • Nicht dokumentierte Funktionen können jederzeit entfernt oder geändert werden.

Best Practices

  • Verwenden Sie den Tag-Wert <id>, um einen Eintrag zu identifizieren.

  • Über den Link self können Sie einen Eintrag abrufen.

  • Über den Link edit können Sie einen Eintrag bearbeiten oder aktualisieren.

  • Verwende den Tag-Wert <yt:videoid> für einen Videoeintrag, um den Wert zu erhalten, mit dem YouTube dieses Video eindeutig identifiziert. Die Video-ID darf nicht aus einem Link geparst werden.

  • Verwende die in den <link>-, <content>- und <gd:feedLink>-Tags angegebenen URLs, um zwischen Feeds zu wechseln. YouTube unterstützt eine begrenzte Anzahl von URLs, die du zuverlässig erstellen kannst, um bestimmte Feeds abzurufen. Außer den unten aufgeführten Feed-URLs sollten Sie keine eigenen Feed-URLs erstellen, da diese möglicherweise unerwartet nicht mehr funktionieren.

    • /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 (weitere Informationen finden Sie im Referenzhandbuch)

  • Versuche nicht, numerische oder alphanumerische IDs aus URLs in einer API-Antwort zu parsen. API-Antworten enthalten bestimmte Tags für IDs, die zu Ressourcen auf der YouTube-Website verweisen, z. B. Video-IDs (<yt:videoid>) und Nutzernamen (<name> und <media:credit>).).

  • Wenn du eine API-Anfrage zum Einfügen (POST) oder Aktualisieren (PUT) von Informationen sendest, kannst du anhand der XML-Antwort auf diese Anfrage feststellen, welche Tag-Werte in der Anfrage tatsächlich von YouTube gespeichert wurden. Wie in den Richtlinien zur Abwärtskompatibilität für API-Anfragen erwähnt, kann YouTube die Informationen ändern, die beim Einfügen oder Aktualisieren einer Ressource gespeichert werden. Das bedeutet, dass einige der Tags in der Anfrage möglicherweise ignoriert werden.

  • Wenn Sie einen XML-Feed abrufen, speichern Sie nicht erkannte XML-Tags und ‑Attribute, die sich auf einen Feedeintrag beziehen, wenn Nutzer in Ihrer Anwendung diesen Eintrag aktualisieren können. Wenn der Nutzer die Ressource aktualisiert, sollte Ihre Anwendung alle nicht erkannten Tags und Attribute in der Aktualisierungsanfrage enthalten. So wird sichergestellt, dass Ihre Anwendung beim Aktualisieren einer Ressource nicht versehentlich Informationen zu neuen API-Funktionen löscht.

    Das folgende Beispiel veranschaulicht diese Best Practice:

    1. Ihre App ermöglicht es Nutzern, eine Videobeschreibung zu aktualisieren.
    2. Ihre Anwendung ruft den Videoeintrag mit der API ab, erkennt aber eines der Tags im Eintrag nicht.
    3. Der Nutzer ändert die Videobeschreibung.
    4. Deine Anwendung muss einen vollständigen Videoeintrag an die API zurücksenden. Der Eintrag muss das nicht erkannte Tag aus Schritt 2 enthalten. Andernfalls wird dieser Wert möglicherweise gelöscht.

  • Prüfen Sie, ob ein Tag vorhanden ist und einen nicht nullwertigen Wert enthält, bevor Sie versuchen, den Tag-Wert anzuzeigen.

  • Wie bereits erwähnt, kann YouTube neue Werte für vorhandene Tags oder Attribute hinzufügen, die Wertelisten enthalten. In der Regel sollte Ihr Code die Werte von XML-Elementen mit aufgezählten Werten analysieren und dann Aktionen für diese Werte definieren. Dies wird auch dann empfohlen, wenn für das Element nur ein möglicher Wert aufgezählt wird.

    Das <media:credit>-Tag gibt beispielsweise den Inhaber eines Videos an. Der einzige dokumentierte Wert für das role-Attribut des Tags ist uploader. Dies gibt an, dass das Video von einem YouTube-Partner hochgeladen wurde. Gemäß dieser Best Practice sollte deine Anwendung prüfen, ob der Wert des role-Attributs des Tags tatsächlich uploader ist, bevor der entsprechende Nutzer als Inhaber des Videos identifiziert wird. So wird verhindert, dass dein Code einen Videoinhaber falsch identifiziert, wenn YouTube andere Arten von Mitwirkenden – z.B. den Regisseur – für ein Video hinzufügt.

    • Wenn ein Tag eine Reihe von Werten hat und Sie den Wert dieses Tags nicht kennen, sollten Sie die gesamte <entry> ignorieren, in der dieses Tag erscheint.

    • Ignoriere einen Feedeintrag für Abos, wenn du den Wert des Attributs term für das Tag <category> nicht kennst, das den Attributwert http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat für scheme hat. Dieses Tag gibt den Typ des Abos an, der durch den Eintrag angegeben ist. Wenn Ihre App den Abotyp nicht erkennt, sollten keine Informationen zu diesem Eintrag angezeigt werden.

    • Wenn ein anderes Attribut eine Reihe von Werten hat und Sie den Wert dieses Attributs nicht kennen, sollten Sie das Tag, in dem das Attribut enthalten ist, ignorieren.

  • Ihr Anwendungscode sollte jederzeit eine yt:error-Nachricht erwarten. Wenn ein API-Vorgang fehlschlägt, sollte Ihre Anwendung den Fehler erkennen und dem Nutzer eine aussagekräftige Meldung anzeigen.

  • YouTube kann jederzeit neue Kategorien zur Klassifizierung von Videos hinzufügen. YouTube kann auch vorhandene Kategorien aktualisieren oder einstellen. Du kannst eine aktuelle Kategoriendatei unter http://gdata.youtube.com/schemas/2007/categories.cat abrufen.

    • Wenn Nutzer in deiner App Videos nach Kategorie durchsuchen oder hochladen können, solltest du wöchentlich eine aktualisierte Kategoriendatei abrufen.

    • Wenn Nutzer in deiner Anwendung nach Videos nach Kategorie suchen können, solltest du auch eine aktualisierte Kategoriendatei abrufen, wenn die API in einer Kategoriesuche einen leeren Feed zurückgibt.

    • Wenn Nutzer in Ihrer App Videos hochladen können, müssen Sie vor dem Hochladen eines Videos auch eine aktualisierte Kategoriendatei abrufen und prüfen, ob die dem hochgeladenen Video zugewiesene Kategorie noch zugewiesen werden kann. Weitere Informationen finden Sie im Referenzhandbuch. Wenn du versuchst, einem Video eine nicht zuweisbare Kategorie zuzuweisen, gibt die API eine Fehlermeldung zurück, bei der der Wert des <code>-Tags deprecated ist.

  • Verwenden Sie die <link>-Tags in einer API-Antwort, um Paginierungslinks für die vorherige und/oder nächste Seite mit Einträgen in einem Feed anzugeben. Weitere Informationen finden Sie im Abschnitt Zwischen den Ergebnissen wechseln des Referenzhandbuchs.