Geriye Dönük Uyumluluk Yönergeleri

Her YouTube Data API isteği, YouTube'un bu isteği işlemek için kullanması gereken API sürümünü belirtebilir. Bir istekte API sürümü belirtilmezse YouTube, bu isteği işlemek için API'nin desteklenen en eski sürümünü kullanır. Şu anda desteklenen en eski sürüm 1'tür. API sürüm numaralarının aşağıdaki özelliklerine dikkat edin:

  • YouTube, yeni bir sürüm numarası atanmamış belirli bir API sürümüne yönelik güncellemeler yayınlayabilir. Bu geriye dönük uyumlu güncellemeler, isteğe bağlı API özellikleri veya hata düzeltmeleri ya da her ikisi de içerebilir.

  • API sürüm numarasının artması, önceki API sürümleriyle uyumlu olmayan değişiklikler içeren bir sürümü tanımlar.

Bu dokümanda, yukarıda listelenen ilk öğe olan belirli bir API sürümündeki güncellemeler için geriye dönük uyumluluk kuralları tanımlanmaktadır. Yönergeler, aşağıdaki API işlev türleri arasında ayrım yapmaya çalışır:

  • Kurallar, API isteklerinizi işlemek için kullanılması gereken API sürümünü değiştirmeseniz bile değişebilecek API işlevlerini tanımlar. Kodunuz bu değişiklikleri sorunsuz bir şekilde işlemelidir. Örneğin, YouTube API yanıtlarına yeni XML etiketleri eklerse kodunuz bu etiketleri yok saymalıdır.

  • Yönergeler, YouTube'un belirli bir API sürümünü güncellerken değiştirmeyi amaçlamadığı API işlevlerini de tanımlar. Diğer bir deyişle, bu işlevin yalnızca YouTube yeni bir API sürümü yayınlarsa değişmesini beklemelisiniz. Ayrıca, kodunuzun bu tür değişiklikleri işlemeye çalışması gerekmez.

Bu belge hakkında

Bu dokümanda aşağıdaki bölümler yer alır:

  • API istekleri bölümünde, HTTP istek üst bilgileri, API istek parametreleri, XML öğe adları (API isteklerinde göründüğü şekilde) ve hatalı oluşturulmuş API istekleri ile ilgili geriye dönük uyumluluk yönergeleri tanımlanmaktadır.

  • API yanıtları bölümünde, XML öğe adlarıyla (API yanıtlarında göründükleri şekilde) ve XML etiketlerinin ve özelliklerinin API yanıtlarında görünme sırasıyla ilgili geriye dönük uyumluluk kuralları tanımlanır.

  • En iyi uygulamalar bölümünde, YouTube API'yi istemci uygulamanızla entegre etmeyle ilgili öneriler yer almaktadır.

API istekleri

Değiştirilmesi amaçlanmayan işlevler

  • Mevcut istek parametreleri.

  • Listelenen değerleri olan parametreler için mevcut parametre değerleri veya bu parametre değerlerinin anlamları.

  • API POST (ekle) veya PUT (güncelle) isteklerinde kullanılan XML öğelerinin adları.

  • Her API isteği türü için gereken HTTP istek üst bilgileri grubu. Bu kural, YouTube'un zorunlu HTTP istek başlıkları eklemeyi veya mevcut isteğe bağlı istek başlıklarını zorunlu hale getirmeyi amaçlamadığı anlamına gelir.

  • İstek strict parametresini kullanmadığı sürece API isteğinde desteklenmeyen parametrelerin yoksayılması davranışı. Bu parametre, YouTube'a geçersiz istek parametreleri içeren API isteklerini reddetme talimatı verir.

Değişebilecek işlevler

  • YouTube, isteğe bağlı istek parametreleri ekleyebilir.

  • YouTube, listelenmiş değer kümelerine sahip mevcut parametreler için yeni değerler ekleyebilir.

  • YouTube, geçerli parametrelerin geçersiz parametre değerleri içerdiği tüm istekleri reddedebilir. Sonuç olarak, ayrıştırma mantığı düzeltilirse aşırı esnek ayrıştırma nedeniyle kabul edilen hatalı oluşturulmuş istekler reddedilebilir.

  • YouTube, isteğe bağlı HTTP istek başlıkları ekleyebilir.

  • YouTube, bir kaynağı eklerken veya güncellerken sakladığı bilgileri değiştirebilir. Ancak bu tür bir karar, ilgili API isteklerinin söz diziminde değişiklik yapılmasını gerektirmez veya bu tür bir değişiklik yapmaz.

  • YouTube, göz atılabilir kategorileri veya yeni yüklenen videoların atanabileceği kategorileri değiştirebilir.

  • Belgelenmemiş işlevler herhangi bir zamanda kaldırılabilir veya değiştirilebilir.

API yanıtları

Değiştirilmesi amaçlanmayan işlevler

  • Mevcut XML etiketi adları.

  • Bu spesifikasyonda tanımlanan ve bir feed girişinde birden çok kez görünen öğelerin sırasını belirlemek için Medya RSS spesifikasyonuna uyma. Örneğin, bir giriş birden fazla <media:thumbnail> etiketi içeriyorsa bu etiketler öneme göre sıralanır.

  • Bir feed'de veya feed girişinde açıklanan öğe türünü tanımlayan <category> etiketinin term özellik değeri. <feed> veya <entry> etiketinde <id> etiketi, giriş tarafından tanımlanan benzersiz kaynağı belirtir ve <category> etiketi, giriş tarafından tanımlanan kaynak türünü belirtir. Bu <category> etiketinde scheme özelliğinin değeri http://schemas.google.com/g/2005#kind'dır ve term özelliğinin değeri, feed girişlerinin videoları, oynatma listesi bağlantılarını, abonelikleri, kişileri mi yoksa başka bir öğe türünü mü tanımladığını belirtir.

Değişebilecek işlevler

  • YouTube, API yanıtlarına yeni XML etiketleri ekleyebilir.

  • YouTube, mevcut XML etiketlerine yeni özellikler ekleyebilir.

  • Mevcut API etiketleri farklı değerlerle tekrarlanabilir. Örneğin, YouTube farklı bir type değeri olan yeni bir <media:restriction> etiketi veya farklı bir scheme ve role değeri olan yeni bir <media:credit> etiketi ekleyebilir.

  • API yanıtındaki XML etiketlerinin ve özelliklerinin sırası değişebilir.

  • İsteğe bağlı alt etiketler API yanıtlarından kaldırılabilir.

  • Belgelenmemiş işlevler herhangi bir zamanda kaldırılabilir veya değiştirilebilir.

En iyi uygulamalar

  • Bir girişi tanımlamak için <id> etiket değerini kullanın.

  • Bir girişi almak için self bağlantısını kullanın.

  • Bir girişi düzenlemek veya güncellemek için edit bağlantısını kullanın.

  • YouTube'un bir videoyu benzersiz şekilde tanımlamak için kullandığı değeri almak üzere video girişi için <yt:videoid> etiket değerini kullanın. Video kimliğini bir bağlantıdan ayrıştırmayın.

  • Feed'ler arasında gezinmek için <link>, <content> ve <gd:feedLink> etiketlerinde tanımlanan URL'leri kullanın. YouTube, belirli feed'leri almak için güvenilir bir şekilde oluşturabileceğiniz sınırlı sayıda URL'yi destekler. Aşağıda listelenen feed URL'leri dışında kendi feed URL'lerinizi oluşturmamanız gerekir. Aksi takdirde, feed'ler beklenmedik bir şekilde çalışmayı durdurabilir.

    • /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 (daha fazla bilgi için referans kılavuzuna bakın)

  • API yanıtındaki URL'lerden sayısal veya alfanümerik tanımlayıcıları ayrıştırmaya çalışmayın. API yanıtları, YouTube web sitesindeki kaynaklara bağlantı veren tanımlayıcılara (ör. video kimlikleri (<yt:videoid>) ve kullanıcı adları (<name> ve <media:credit>).

  • Bilgi eklemek (POST) veya güncellemek (PUT) için bir API isteği gönderirseniz istekteki hangi etiket değerlerinin YouTube tarafından gerçekten depolandığını belirlemek için söz konusu istek için XML yanıtını kullanın. API istekleriyle ilgili geriye dönük uyumluluk kurallarında belirtildiği gibi, YouTube bir kaynak eklerken veya güncellerken sakladığı bilgileri değiştirebilir. Bu da istekteki etiketlerin bazılarının yoksayılabileceği anlamına gelir.

  • Bir XML feed'ini aldığınız zaman, uygulamanız kullanıcının ilgili girişi güncellemesine olanak tanıyorsa feed girişiyle ilgili tanınmayan XML etiketlerini ve özelliklerini saklayın. Kullanıcı kaynağı güncelliyorsa uygulamanız, tanınmayan etiketleri ve özellikleri güncelleme isteğine dahil etmelidir. Bu uygulama, uygulamanızın bir kaynağı güncelleme sürecinde yeni API özellikleriyle ilgili bilgileri yanlışlıkla silmesini önler.

    Aşağıdaki örnekte bu en iyi uygulama gösterilmektedir:

    1. Uygulamanız, kullanıcıların video açıklamalarını güncellemelerine olanak tanır.
    2. Uygulamanız, API'yi kullanarak video girişini alır ancak girişteki etiketlerden birini tanımaz.
    3. Kullanıcı video açıklamasını değiştirir.
    4. Uygulamanızın, API'ye eksiksiz bir video girişi göndermesi gerekir. Girişte, 2. adımdaki tanınmayan etiketin yer alması gerekir. Aksi takdirde bu değer silinebilir.

  • Etiket değerini göstermeye çalışmadan önce etiketin var olduğunu ve null olmayan bir değer içerdiğini onaylayın.

  • Yukarıda belirtildiği gibi YouTube, listelenmiş değer kümeleri içeren mevcut etiketler veya özellikler için yeni değerler ekleyebilir. Kural olarak, kodunuz, listelenmiş değer kümeleri içeren XML öğelerinin değerlerini ayrıştırmalı ve ardından bu değerlere uygun işlemleri tanımlamalıdır. Bu uygulama, öğe için yalnızca bir olası değer sayılmış olsa bile önerilir.

    Örneğin, <media:credit> etiketi bir videonun sahibini tanımlar. Etiketin role özelliği için belgelenmiş tek değer uploader'dur. Bu değer, videonun bir YouTube iş ortağı tarafından yüklendiğini gösterir. Bu en iyi uygulama, uygulamanızın ilgili kullanıcıyı video sahibi olarak tanımlamadan önce etiketin role özelliğinin değerinin gerçekten uploader olduğunu onaylamasını zorunlu kılar. (Bu önlem, YouTube bir videoya yönetmen gibi başka bir jenerik türü eklerse kodunuzun video sahibini yanlış tanımlamasını önler.)

    • Bir etiketin listelenmiş bir değer grubu varsa ve bu etiketin değerini tanımıyorsanız bu etiketin göründüğü <entry> değerinin tamamını yoksaymanız gerekir.

    • http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat scheme özelliği değerine sahip <category> etiketi için term özelliğinin değerini tanımıyorsanız abonelikler feed girişini yoksayabilirsiniz. Bu etiket, giriş tarafından tanımlanan abonelik türünü tanımlar. Uygulamanız abonelik türünü tanımıyorsa ilgili girişle ilgili bilgileri göstermemelidir.

    • Başka bir özelliğin listelenmiş bir değer grubu varsa ve bu özelliğin değerini tanımıyorsanız özelliğin göründüğü etiketi yoksaymanız gerekir.

  • Uygulama kodunuza yt:error mesajı gönderilebilir. Bir API işleminin başarısız olması durumunda uygulamanız hatayı tanımlamalı ve kullanıcıya anlamlı bir mesaj göstermelidir.

  • YouTube, videoları sınıflandırmak için dilediğinde yeni kategoriler ekleyebilir. YouTube, mevcut kategorileri de güncelleyebilir veya desteğini sonlandırabilir. http://gdata.youtube.com/schemas/2007/categories.cat adresinden geçerli kategoriler dosyasını alabilirsiniz.

    • Uygulamanız kullanıcıların videolara kategorilerine göre göz atmasına veya video yüklemesine olanak tanıyorsa güncellenmiş kategoriler dosyasını haftalık olarak alın.

    • Uygulamanız kullanıcıların videolara kategoriye göre göz atmasına olanak tanıyorsa API, kategori aramasına yanıt olarak boş bir feed döndürürse güncellenmiş bir kategoriler dosyası da alın.

    • Uygulamanız kullanıcıların video yüklemesine olanak tanıyorsa video yüklemeden önce güncellenmiş bir kategoriler dosyası da alın ve yüklenen videoyla ilişkili kategorinin hâlâ atanabilir durumda olduğunu onaylayın. Daha fazla bilgi için referans kılavuzuna göz atın. (Bir videoyu atanamayan bir kategoriye atamaya çalışırsanız API'nin, <code> etiketinin değerinin deprecated olduğu bir hata mesajı döndüreceğini unutmayın.)

  • Bir feed'deki girişlerin önceki ve/veya sonraki sayfası için sayfalandırma bağlantılarını tanımlamak üzere API yanıtında <link> etiketlerini kullanın. Daha fazla bilgi için referans kılavuzunun Sonuçlar arasında sayfalama bölümüne bakın.