Apple'ın podcast API'si binlerce bölüm raporluyor ama sessizce çok daha azını döndürüyor

dev.to'da yayımlanan ölçümlere göre Apple'ın herkese açık podcast API'si, bir dizinin 2.752 bölümü olduğunu raporlayıp sonra bunların sadece 44 tanesini geri veriyor. Eksik sessizce gerçekleşiyor: yanıtlar HTTP 200 ile geliyor; ne bir hata kodu var ne de bir şeyin atlandığına dair ipucu veren bir alan.

İşin içindeki servis, anahtar gerektirmeyen iTunes JSON API'si — listeleri, aramayı, dizi sorgulamayı, bölümleri ve yorumları kapsayan endpoint ailesi — ve tam da API anahtarı gerektirmediği için podcast araçları için yaygın bir başlangıç noktası.

Kendini hiç belli etmeyen 200 tavanı

Yazar, lookup endpoint'ini Lex Fridman Podcast üzerinde entity=podcastEpisode parametresiyle test etti ve limit parametresini kademeli olarak yükseltti. limit=200'de yanıt 201 satır içeriyordu: 200 bölüm artı dizinin kendi track kaydı; bu kayıt aynı dizide geliyor ve wrapperType değeriyle ayıklanması gerekiyor. limit=201, 300 ve 1000'de API, bayta kadar aynı bir gövde döndürdü. Yanıtta hiçbir şey bir şeyin kırpıldığını göstermedi.

offset kabul ediliyor ama yok sayılıyor

Sayfalama da çalışmıyor. Gönderiye göre, lookup endpoint'inde test edilen her offset değeri aynı ilk bölümü ve aynı trackId'yi üretti. Yazar ardından search endpoint'ini hem podcast hem müzik sorgularında kontrol etti ve offset'ten bağımsız olarak tam sonuç listelerinin özdeş olduğunu gördü; geri dönülecek bir cursor alanı da yok. Dolayısıyla 200 satırlık tavan mutlak bir üst sınır, sayfa boyutu değil.

Bazı diziler 200'ün çok altını alıyor

Üst sınır diziden dizive de değişiyor. limit=1000 ile istenen dört podcast, her dizinin kendi kaydındaki trackCount değeriyle karşılaştırıldığında:

• Dan Carlin's Hardcore History: 13 bölümün 13'ü, tam.
• Lex Fridman Podcast: 502'nin 200'ü; döndürülen en eski bölümün tarihi 2022-07-17.
• NPR'den Up First: 1.425'in 200'ü.
• The Daily: 2.752'nin 44'ü.

Tuhaf durum The Daily'de. Döndürülen 44 bölüm 307 güne yayılıyor; oysa hafta içi her gün yayımlanan bir dizi bu sürede kabaca 215 bölüm üretirdi. Tarihler, gerçekten günlük olan yakın bir uç ile haftalığa seyrelmiş daha eski bir uç gösteriyor; ardışık kayıtlar arasındaki boşluklar 21 güne kadar çıkıyor. Analize göre, Apple'ın diziye ait indeksi temiz bir sınırda durmak yerine geriye gittikçe seyreliyor.

Pratik zarar analitik alanda. Bu veriden aylık bölüm sayısı, yayımlama temposu ya da çeyrek başına ortalama süre hesaplarsanız, büyüklük mertebesi kadar sapabilen ama kendinden emin görünen bir rakam elde edersiniz; payload'ın içinde hiçbir yerde eksik veri sinyali yok. Up First ve The Daily'nin ikisi de günlük haber podcast'leri; biri yoğun 200 bölüm veriyor, öteki seyrek 44 bölüm veriyor ve istekle ilgili hiçbir şey size hangisini bekleyeceğinizi söylemiyor.

Bedava bir tamlık kontrolü

Gönderinin merkezindeki öneri ek bir istek gerektirmiyor. Aynı payload'daki dizi kaydı, gerçek katalog büyüklüğü olan trackCount'u taşıyor. Bunu fiilen döndürülen podcastEpisode satır sayısıyla karşılaştırın: 2.752'ye karşı 44 kırpılmış, 13'e karşı 13 tam demektir. Sayılar yetmediğinde çıktı tam arşiv olarak değil, örneklem olarak etiketlenmelidir — bunu özellikle önemli kılan, tavanın sabit bir 200 olmamasıdır.

RSS alternatifi de bir arşiv değil

Standart çözüm — dizi kaydındaki feedUrl'yi okuyup yayımcının RSS'ini ayrıştırmak — daha iyi ama tam değil. Lex Fridman'ın beslemesi 502 bölümün tamamını, Ağustos 2018'e kadar geriye doğru içeriyor. Up First'ın beslemesi 1.425 bölümün 500'ünü taşıyor, yaklaşık yüzde 35. The Daily'ninki ise 2.752'nin 66'sını, yaklaşık yüzde 2,4'ünü içeriyor ve bu 66 öğe 2021'e kadar uzanıyor; yani beslemenin kendisi de tıpkı Apple'ın indeksi gibi örneklenmiş. Yayımcılar beslemeleri buduyor, çünkü podcast uygulamaları onları sürekli yeniden çekiyor ve kimse her yenilemede devasa bir XML dosyası sunmak istemiyor.

RSS yine de daha zengin bir kaynak; Apple'ın JSON'ının hiç sunmadığı alanları açığa çıkarıyor: bölüm türü, tam HTML show notları, enclosure bayt boyutları ve transcript URL'leri gibi. Ama uzun soluklu, yüksek frekanslı diziler için hiçbir herkese açık endpoint tüm arşivi sunmuyor; o arşiv yalnızca yayımcının kendi CMS'inde var. The Daily için herkesin erişebildiği iki kaynak da kataloğun yüzde 97'den fazlasını kaçırıyor. Yazar, kendi scraper'ının artık Apple sonuçlarını 200'de kestiğini ve bölümleri yayımcının beslemesinden çekme seçeneği sunduğunu, böylece etkin sınırı lookup API'ye geri düşme mekanizmasıyla 20.000'e çıkardığını ekliyor.

Neden önemli

Sessiz kesme, hatadan daha kötü. Apple'ın herkese açık API'si üzerine arama indeksleri, analitik ya da keşif araçları inşa eden herkes, yanıtlardan tek başına fark etmenin hiçbir yolu olmadan eksik veri içeri alacak; iki hata modu — mutlak 200 satır tavanı ve yüksek frekanslı diziler için seyrelen indeksler — bilerek yoklanmadıkça görünmez. trackCount ile döndürülen satır sayısı karşılaştırması her istemcinin benimseyebileceği sıfır maliyetli bir güvence ve eksikliği işaretlemek, güvenebileceğiniz veri ile yalnızca güvenilir görünen veriyi birbirinden ayıran şeydir.