Geriye dönük uyumluluk kuralları

Her YouTube Data API isteği, YouTube'un bu isteği işlemek için kullanması gereken API sürümünü belirtebilir. Bir istek bir API sürümünü belirtmiyorsa YouTube, bu isteği işlemek için desteklenen en eski API sürümünü kullanır. Desteklenen en eski sürüm şu anda 1. Lütfen API sürüm numaralarının aşağıdaki özelliklerini unutmayın:

• YouTube, sürüme yeni sürüm numarası atanmamış belirli bir API sürümünde güncellemeler yayınlayabilir. Bu geriye dönük uyumlu güncellemeler arasında isteğe bağlı API özellikleri, hata düzeltmeleri veya her ikisi birden bulunabilir.

• API sürüm numarasındaki artış, önceki API sürümleriyle uyumsuz olan değişiklikleri içeren bir sürümü tanımlar.

Bu dokümanda, yukarıda listelenen ilk öğe olan belirli bir API sürümüyle ilgili güncellemeler için geriye dönük uyumluluk kuralları tanımlanmaktadır. Yönergeler, aşağıdaki API işlevi türlerini birbirinden ayırt etmeye çalışır:

• Yönergeler, 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 bozulmadan işlemelidir. Örneğin, YouTube API API'lerine yeni XML etiketleri eklerse kodunuz bu etiketleri yoksaymalıdır.

• Yönergeler, belirli bir API sürümünü güncellerken YouTube'un değiştirmek istemediği API işlevlerini de tanımlar. Diğer bir ifadeyle, YouTube'un yeni bir API sürümü sunması ve kodunuzun bu tür değişiklikleri yapmaya çalışması gerekmeden bu işlevin değişmesini bekleyebilirsiniz.

Bu doküman hakkında

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

• API istekleri bölümü HTTP istek başlıkları, API istek parametreleri, XML öğesi adları (API isteklerinde göründükleri gibi) ve yanlış oluşturulmuş API istekleriyle ilgili geriye dönük uyumluluk yönergelerini tanımlar.

• API yanıtları bölümü, XML öğesi adlarıyla ilgili (API yanıtlarında göründüğü şekilde) geriye dönük uyumluluk yönergelerini ve XML etiketlerinin ve özelliklerin API yanıtlarında görünme sırasını tanımlar.

• En iyi uygulamalar bölümünde, YouTube API'yi istemci uygulamanızla entegre etmeye ilişkin öneriler özetlenmektedir.

API istekleri

Değişmeyen işlevler

• Mevcut istek parametreleri.

• Numaralı değerlere sahip parametreler için mevcut parametre değerleri veya bu parametre değerlerinin anlamları.

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

• Her API isteği türü için gerekli olan HTTP istek başlıkları grubudur. Bu kural, YouTube'un gerekli HTTP istek başlıklarını eklemeyi veya mevcut isteğe bağlı istek başlıklarını değiştirmeyi amaçlamadığı anlamına gelir.

• Bir API'de desteklenmeyen parametreleri yoksayma davranışı, istek strict parametresini kullanmadığı sürece geçersizdir. Bu parametre, YouTube'a geçersiz istek parametreleri içeren bir API isteğini reddetmesini bildirir.

Değişebilecek işlevler

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

• YouTube, numaralandırılmış değer gruplarına 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. Bu nedenle, aşırı esnek ayrıştırma nedeniyle kabul edilmeyen hatalı oluşturulmuş istekler, ayrıştırma mantığı düzeltilirse reddedilebilir.

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

• YouTube bir kaynak eklerken veya güncellerken sakladığı bilgileri (depolar) değiştirebilir. Ancak bu tür bir karar, ilgili API isteklerinin söz dizimini etkilemez veya değiştirmez.

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

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

API yanıtları

Değişmeyen işlevler

• Mevcut XML etiketi adları.

• Bu spesifikasyonda tanımlanan ve bir feed girişinde birden fazla kez görünen öğelerin sırasını belirlemek için Medya RSS spesifikasyonunu izleme. Örneğin, bir giriş birden fazla <media:thumbnail> etiketi içeriyorsa bu etiketler önem derecesine 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> etiketi içinde <id> etiketi, girişin tanımladığı benzersiz kaynağı belirtir. <category> etiketi ise giriş tarafından açıklanan kaynağın türünü tanımlar. Bu <category> etiketi için şema özelliğinin değeri http://schemas.google.com/g/2005#kind, terim özelliğinin değeri ise feed girişlerinin videoları, oynatma listesi bağlantılarını, abonelikleri, kişileri veya başka bir öğe türünü açıklayıp açıklamadığını gösterir.

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ğerine sahip yeni bir <media:restriction> etiketi veya farklı bir scheme ve role değerine sahip yeni bir <media:credit> etiketi ekleyebilir.

• XML etiketlerinin ve API yanıtındaki özelliklerin 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 bu videoyu benzersiz şekilde tanımlamak için kullandığı değeri elde etmek istiyorsanız video girişi için <yt:videoid> etiket değerini kullanın. Bağlantıdaki video kimliğini ayrıştırmayın.

• Feed'ler arasında gezinmek için <link>, <content> ve <gd:feedLink> etiketlerinde belirtilen 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 bu feed URL'lerinin yanı sıra, kendi feed'lerini de beklenmedik şekilde çalışmayabileceği için oluşturmamalısınız.

  • /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ılavuzunu inceleyin)

• API yanıtındaki URL'lerden gelen 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ılar için video kimlikleri (<yt:videoid>) ve kullanıcı adları (<name> ve <media:credit>). gibi) gibi belirli etiketler içerir

• 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 bu isteğe verilen XML yanıtını kullanın. API istekleri için geriye dönük uyumluluk yönergelerinde belirtildiği üzere YouTube, bir kaynağı eklerken veya güncellerken sakladığı bilgileri (depolar) değiştirebilir. Bu durumda, istekteki bazı etiketler yoksayılabilir.

• Bir XML feed'i aldığınızda, uygulamanız kullanıcının bu girişi güncellemesini etkinleştirdiyse bir feed girişiyle ilgili tanınmayan XML etiketlerini ve özelliklerini depolayın. Kullanıcı kaynağı güncellerse uygulamanız güncelleme isteğine tanınmayan etiketler ve özellikler içermelidir. Bu uygulamayla uygulamanızın bir kaynağı güncelleme sürecinde yeni API özellikleriyle ilgili bilgileri yanlışlıkla silmemesini sağlayabilirsiniz.

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

  1. Uygulamanız bir kullanıcının video açıklamasını güncellemesini sağlar.
  2. Uygulamanız, video girişini API kullanarak alır ancak girişteki etiketlerden birini tanımaz.
  3. Kullanıcı, video açıklamasını değiştirir.
  4. Uygulamanızın eksiksiz bir video girişini API'ye geri göndermesi gerekiyor. Girişin 2. adımdaki tanınmayan etiketi içermesi gerekir; aksi takdirde bu değer silinebilir.

• Etiket değerini görüntülemeye çalışmadan önce bir etiketin mevcut olduğunu ve boş olmayan bir değer içerdiğini onaylayın.

• Yukarıda belirtildiği gibi YouTube, mevcut etiketler veya numaralandırılmış değer grupları içeren özellikler için yeni değerler ekleyebilir. Kuralınız olarak, numaralandırılmış değer gruplarına sahip XML öğelerinin değerlerini ayrıştırmalı ve ardından bu değerlere uygun işlemleri tanımlamalısınız. Bu uygulama, öğe için yalnızca bir olası değer numaralandırılmış olsa bile önerilir.

  Örneğin, <media:credit> etiketi videonun sahibini belirler. Etiketin role özelliği için belgelenen tek değer uploader. Bu değer, videonun bir YouTube iş ortağı tarafından yüklendiğini gösterir. Bu en iyi uygulama, ilgili kullanıcıyı video sahibi olarak tanımlamadan önce uygulamanızın, etiketin role özelliğinin değerinin gerçekten uploader olduğunu onaylamasını gerektirir. (Bu önlem, YouTube bir video için başka kredi türleri (ör. yönetmen) eklerse kodunuzun video sahibini yanlış şekilde tanımlamamasını sağlar.)

  • Bir etikette numaralandırılmış değer grubu varsa ve bu etiketin değerini tanımıyorsanız etiketin içinde göründüğü <entry> değerini yoksaymalısınız.

  • scheme özellik değeri http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat olan <category> etiketi için term özelliğinin değerini bilmiyorsanız abonelik özet akışı girişini yoksayın. Bu etiket, giriş tarafından tanımlanan aboneliğin türünü tanımlar. Uygulamanız abonelik türünü tanımıyorsa o girişle ilgili bilgileri görüntülememelidir.

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

• Uygulama kodunuz her zaman bir yt:error mesajı olmalıdır. Bir API işleminin başarısız olması durumunda, uygulamanız hatayı belirlemeli ve kullanıcıya anlamlı bir mesaj göstermelidir.

• YouTube, videoları sınıflandırmak için istediği zaman yeni kategoriler ekleyebilir. YouTube mevcut kategorileri güncelleyebilir veya kullanımdan kaldırabilir. http://gdata.youtube.com/schemas/2007/category.cat adresinden mevcut bir kategori dosyası alabilirsiniz.

  • Uygulamanız kullanıcıların kategorilere göre göz atmasına veya video yüklemesine izin veriyorsa haftalık olarak güncellenen bir kategori dosyası alın.

  • Uygulamanız, kullanıcıların kategoriye göre göz atabilmesini sağlıyorsa API bir kategori aramasına yanıt olarak boş bir feed döndürüyorsa güncellenmiş bir kategori dosyası da alın.

  • Uygulamanız, kullanıcıların video yüklemesine izin veriyorsa video yüklemeden önce güncellenmiş bir kategori dosyası da alın ve yüklenen videoyla ilişkili kategorinin hâlâ atanabilir olduğunu onaylayın. Daha fazla bilgi için referans kılavuzunu inceleyin. (Atanamayan bir kategoriye video atamaya çalışırsanız API'nin <code> etiketi değeri deprecated olan bir hata mesajı döndüreceğini unutmayın.)

• Bir feed'deki girişlerin önceki ve/veya sonraki sayfasına ait sayfalara ayırma bağlantılarını tanımlamak için API yanıtındaki <link> etiketlerini kullanın. Daha fazla bilgi için referans kılavuzunun Sonuçlara göz atma bölümüne bakın.