Wytyczne dotyczące zgodności wstecznej

Każde żądanie do interfejsu YouTube Data API może określać wersję interfejsu API, której YouTube powinien użyć do obsługi tego żądania. Jeśli żądanie nie określa wersji interfejsu API, YouTube użyje najstarszej obsługiwanej wersji interfejsu API do obsługi tego żądania. Najstarsza obsługiwana wersja to obecnie 1. Zwróć uwagę na te cechy numerów wersji interfejsu API:

• YouTube może publikować aktualizacje konkretnej wersji interfejsu API, dla której nie przypisano nowej numeracji wersji. Te zgodne wstecznie aktualizacje mogą zawierać opcjonalne funkcje interfejsu API, poprawki błędów lub jedno i drugie.

• Zwiększenie numeru wersji interfejsu API oznacza wydanie, które zawiera zmiany niezgodne z poprzednimi wersjami interfejsu API.

Ten dokument określa wytyczne dotyczące zgodności wstecznej w przypadku aktualizacji do konkretnej wersji interfejsu API (pierwszy punkt na liście). Wytyczne mają na celu rozróżnienie tych typów funkcji interfejsu API:

• Wytyczne określają funkcje interfejsu API, które mogą ulec zmianie, nawet jeśli nie zmodyfikujesz wersji interfejsu API, która powinna być używana do obsługi żądań interfejsu API. Twój kod powinien obsługiwać te zmiany bez powodowania błędów. Jeśli np. YouTube doda nowe tagi XML do odpowiedzi interfejsu API, Twój kod powinien je zignorować.

• Wytyczne określają też funkcje interfejsu API, których YouTube nie zamierza zmieniać podczas aktualizacji konkretnej wersji interfejsu API. Inaczej mówiąc, ta funkcja może się zmienić tylko wtedy, gdy YouTube wyda nową wersję interfejsu API. Twój kod nie musi obsługiwać tego typu zmian.

Informacje o tym dokumencie

Niniejszy dokument obejmuje następujące sekcje:

• W sekcji Żądania do interfejsu API znajdziesz wskazówki dotyczące zgodności wstecznej dotyczące nagłówków żądań HTTP, parametrów żądań interfejsu API, nazw elementów XML (jak są one wyświetlane w żądaniach interfejsu API) oraz źle sformułowanych żądań interfejsu API.

• W sekcji Odpowiedzi interfejsu API znajdziesz wskazówki dotyczące zgodności wstecznej dotyczące nazw elementów XML (takich, jak występują w odpowiedziach interfejsu API) oraz kolejności, w jakiej tagi i atrybuty XML występują w odpowiedziach interfejsu API.

• W sekcji Sprawdzone metody znajdziesz rekomendacje dotyczące integracji interfejsu YouTube API z aplikacją klienta.

Żądania do interfejsu API

Funkcje, które nie powinny ulec zmianie

• Istniejące parametry żądania.

• Dotychczasowe wartości parametrów, które mają wartości wyliczeniowe, lub znaczenie tych wartości.

• Nazwy elementów XML używanych w żądaniach POST (insert) lub PUT (update) interfejsu API.

• Zestaw nagłówków żądań HTTP, które są wymagane w przypadku każdego typu żądania interfejsu API. Oznacza to, że YouTube nie zamierza dodawać wymaganych nagłówków żądania HTTP ani zmieniać istniejących opcjonalnych nagłówków żądania, aby stały się wymagane.

• ignorowanie nieobsługiwanych parametrów w żądaniu interfejsu API, chyba że żądanie zawiera parametr strict, który instruuje YouTube, aby odrzucił żądanie interfejsu API zawierające nieprawidłowe parametry żądania;

Funkcje, które mogą ulec zmianie

• YouTube może dodać opcjonalne parametry żądania.

• YouTube może dodawać nowe wartości dotychczasowych parametrów, które mają wyliczone zbiory wartości.

• YouTube może odrzucić żądanie, w którym prawidłowe parametry zawierają nieprawidłowe wartości. W efekcie źle sformułowane żądania, które zostały zaakceptowane z powodu zbyt łagodnego parsowania, mogą zostać odrzucone, jeśli logika parsowania zostanie poprawiona.

• YouTube może dodać opcjonalne nagłówki żądania HTTP.

• Podczas wstawiania lub aktualizowania zasobu YouTube może zmienić informacje, które zapisuje. Taka decyzja nie wpłynie jednak na składnię odpowiednich żądań interfejsu API ani nie będzie wymagać jej zmiany.

• YouTube może zmienić zestaw kategorii, które można przeglądać lub do których można przypisać nowo przesłane filmy.

• Nieudokumentowane funkcje mogą zostać usunięte lub zmienione w dowolnym momencie.

Odpowiedzi interfejsu API

Funkcje, które nie powinny ulec zmianie

• nazwy istniejących tagów XML;

• stosować specyfikację Media RSS, aby określić kolejność elementów zdefiniowanych w tej specyfikacji i występujących wielokrotnie w rekordzie kanału; Jeśli na przykład wpis zawiera wiele tagów <media:thumbnail>, są one uporządkowane według ważności.

• Wartość atrybutu term tagu <category>, który identyfikuje typ elementu opisanego w pliku danych lub wpisie w pliku danych. W tagu <feed> lub <entry> tag <id> określa unikalny zasób zidentyfikowany przez wpis, a tag <category> określa rodzaj zasobu opisanego przez wpis. W przypadku tego tagu <category> wartość atrybutu scheme to http://schemas.google.com/g/2005#kind, a wartość atrybutu term wskazuje, czy wpisy w pliku danych opisują filmy, linki do playlist, subskrypcje, kontakty czy inny typ elementu.

Funkcje, które mogą ulec zmianie

• YouTube może dodawać nowe tagi XML do odpowiedzi interfejsu API.

• YouTube może dodawać nowe atrybuty do dotychczasowych tagów XML.

• Istniejące tagi interfejsu API mogą być powtarzane z różnymi wartościami. Na przykład YouTube może dodać nowy tag <media:restriction> z inną wartością type lub nowy tag <media:credit> z innymi wartościami scheme i role.

• Kolejność tagów i atrybutów XML w odpowiedzi interfejsu API może się zmienić.

• Opcjonalne tagi podrzędne mogą zostać usunięte z odpowiedzi na żądania do interfejsów API.

• Nieudokumentowane funkcje mogą zostać usunięte lub zmienione w dowolnym momencie.

Sprawdzone metody

• Aby zidentyfikować wpis, użyj wartości tagu <id>.

• Aby pobrać wpis, kliknij link self.

• Aby edytować lub zaktualizować wpis, kliknij link edit.

• Użyj wartości tagu <yt:videoid> w przypadku wpisu wideo, aby uzyskać wartość, której YouTube używa do jednoznacznego zidentyfikowania tego filmu. Nie analizuj identyfikatora filmu z linku.

• Aby poruszać się między kanałami, używaj adresów URL zdefiniowanych w tagach <link>, <content> i <gd:feedLink>. YouTube obsługuje ograniczony zestaw adresów URL, które możesz tworzyć, aby pobierać określone kanały danych. Poza adresami URL plików danych wymienionymi poniżej nie należy tworzyć własnych adresów URL plików danych, ponieważ mogą one nieoczekiwanie przestać działać.

  • /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 (więcej informacji znajdziesz w przewodniku)

• Nie próbuj analizować identyfikatorów numerycznych ani alfanumerycznych z adresów URL w odpowiedzi interfejsu API. Odpowiedzi interfejsu API zawierają określone tagi dla identyfikatorów, które łączą się z zasobami w witrynie YouTube, takie jak identyfikatory filmów (<yt:videoid>) i nazwy użytkowników (<name> i <media:credit>).).

• Jeśli przesyłasz żądanie interfejsu API, aby wstawić (POST) lub zaktualizować (PUT) informacje, użyj odpowiedzi XML na to żądanie, aby określić, które wartości tagów w żądaniu zostały faktycznie zapisane przez YouTube. Jak wyjaśniono w wytycznych dotyczących zgodności wstecznej w przypadku żądań interfejsu API, YouTube może zmienić informacje, które zachowuje (przechowuje), podczas wstawiania lub aktualizowania zasobu, co oznacza, że niektóre tagi w żądaniu mogą zostać zignorowane.

• Gdy pobierasz plik danych XML, przechowuj niezidentyfikowane tagi i atrybuty XML powiązane z rekordem pliku danych, jeśli Twoja aplikacja umożliwia użytkownikowi aktualizowanie tego rekordu. Jeśli użytkownik zaktualizuje zasób, aplikacja powinna uwzględnić w prośbie o zaktualizowanie wszystkie niezidentyfikowane tagi i atrybuty. Dzięki temu aplikacja nie usunie przez przypadek informacji związanych z nowymi funkcjami interfejsu API podczas aktualizowania zasobu.

  Ten przykład ilustruje tę sprawdzoną metodę:

  1. Aplikacja umożliwia użytkownikowi aktualizowanie opisu filmu.
  2. Aplikacja pobiera wpis o filmie za pomocą interfejsu API, ale nie rozpoznaje jednego z tagów w tym wpisie.
  3. Użytkownik modyfikuje opis filmu.
  4. Aplikacja musi wysłać do interfejsu API pełny wpis wideo. Wpis musi zawierać niezidentyfikowany tag z etapu 2. W przeciwnym razie ta wartość może zostać usunięta.

• Zanim spróbujesz wyświetlić wartość tagu, sprawdź, czy tag istnieje i czy zawiera wartość inną niż null.

• Jak już wspomnieliśmy, YouTube może dodawać nowe wartości do istniejących tagów lub atrybutów, które mają wyliczone zbiory wartości. Zazwyczaj kod powinien analizować wartości elementów XML, które mają wyliczone zbiory wartości, a potem definiować działania odpowiednie do tych wartości. Zalecamy to nawet wtedy, gdy dla elementu występuje tylko jedna możliwa wartość.

  Na przykład tag <media:credit> wskazuje właściciela filmu. Jedyną udokumentowaną wartość atrybutu role tagu jest uploader, co oznacza, że film został przesłany przez partnera YouTube. Zgodnie z tymi zaleceniami aplikacja powinna potwierdzić, że wartość atrybutu role tagu to rzeczywiście uploader, zanim zidentyfikuje odpowiadającego mu użytkownika jako właściciela filmu. (Ta ostrożność ma na celu zapewnienie, że Twój kod nie zidentyfikuje nieprawidłowo właściciela filmu, jeśli YouTube doda do niego inne typy informacji, np. o reżyserze).

  • Jeśli tag ma wyliczany zbiór wartości, a nie znasz jego wartości, zignoruj cały element <entry>, w którym występuje ten tag.

  • Ignoruj wpis w pliku danych dotyczący subskrypcji, jeśli nie rozpoznajesz wartości atrybutu term dla tagu <category>, który ma wartość atrybutu scheme równą http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. Ten konkretny tag określa typ subskrypcji zidentyfikowany przez wpis. Jeśli aplikacja nie rozpoznaje typu subskrypcji, nie powinna wyświetlać informacji o tym wpisie.

  • Jeśli jakikolwiek inny atrybut ma wyliczany zbiór wartości, a Ty nie rozpoznajesz wartości tego atrybutu, zignoruj tag, w którym się on pojawia.

• Kod aplikacji powinien być gotowy do obsługi wiadomości yt:error w dowolnym momencie. Jeśli operacja interfejsu API zakończy się niepowodzeniem, aplikacja powinna wykryć błąd i wyświetlić użytkownikowi odpowiedni komunikat.

• YouTube może w dowolnym momencie dodawać nowe kategorie do klasyfikowania filmów. YouTube może też aktualizować i wycofywać istniejące kategorie. Aktualny plik kategorii możesz pobrać z adresu http://gdata.youtube.com/schemas/2007/categories.cat.

  • Jeśli Twoja aplikacja umożliwia użytkownikom przeglądanie filmów według kategorii lub przesyłanie filmów, pobieraj co tydzień zaktualizowany plik kategorii.

  • Jeśli Twoja aplikacja umożliwia użytkownikom przeglądanie filmów według kategorii, pobierz zaktualizowany plik kategorii, jeśli interfejs API zwróci pusty plik danych w odpowiedzi na wyszukiwanie kategorii.

  • Jeśli Twoja aplikacja umożliwia użytkownikom przesyłanie filmów, przed przesłaniem filmu pobierz zaktualizowany plik kategorii i sprawdź, czy kategoria powiązana z przesłanym filmem nadal może być przypisana. Więcej informacji znajdziesz w przewodniku. (jeśli spróbujesz przypisać film do kategorii, do której nie można przypisać filmu, interfejs API zwróci komunikat o błędzie, w którym wartość tagu <code> to deprecated).

• Użyj tagów <link> w odpowiedzi interfejsu API, aby zidentyfikować linki stronowania do poprzedniej lub następnej strony wpisów w pliku danych. Więcej informacji znajdziesz w przewodniku na temat przechodzenia do kolejnych stron wyników.