Müzik Dağıtım API Entegrasyonu Nasıl Yapılır

Bir müzik dağıtım API’sine entegre olmak, kendi sisteminizi; bir kataloğu içe alan, meta verilerini doğrulayan, yayınları streaming mağazalarına teslim eden ve telif ile analiz verilerini geri okuyan bir hatta bağlamak demektir. Plak şirketlerini, yayınları ve parçaları bir web formu yerine HTTP çağrılarıyla oluşturur, her yayını doğrulama için gönderir, DSP”lere teslimatı tetikler, ardından stream’leri ve hesap özetlerini kendi kayıtlarınızla mutabakat için çekersiniz. Çağrıların kendisi işin kolay kısmıdır. Asıl iş, müzik meta verilerini doğru modellemek, asenkron adımları yönetmek ve bir teslimatın reddedilerek döndüğü günü karşılayacak şekilde inşa etmektir.

Bu rehber, o entegrasyonu gerçekte inşa edeceğiniz sırayla ele alır: kimlik doğrulama, bir yayın oluşturup teslim etme, doğrulama ve hataları yönetme, ardından parayı ve sayıları geri okuma. Aşağıdaki endpoint taslakları LabelGrid”in genel API”sini kullanır, ama bu yapı çoğu dağıtım platformu için geçerlidir. Kesin alanlar, parametreler ve hata kodları genel API dokümantasyonunda yer alır; yani bu bir haritadır, alan alan referans değil.

Bir Müzik Dağıtım API”si Gerçekte Ne Yapar?

Bir dağıtım API”si, yayın yaşam döngüsünü endpoint”ler olarak sunar. Dört aşama vardır ve her entegrasyon bunlardan aynı sırayla geçer. Birincisi, katalog aktarımı: kataloğunuzu oluşturan plak şirketlerini, yayınları ve parçaları oluşturur, meta verileri ve ses dosyalarını eklersiniz. İkincisi, doğrulama: bir yayını herhangi bir yere gitmeden önce mağaza kurallarına göre kontrol edersiniz. Üçüncüsü, teslimat: doğrulanan yayını streaming platformlarına ve mağazalara dağıtırsınız. Dördüncüsü, geri okuma: müzik yayına girdikten sonra ne olduğunu kendi sisteminizin bilmesi için analiz ve telif hesap özetlerini çekersiniz.

Teslimatın altında, bir mağazanın içe alabilmesi için bir yayını ve sesini tanımlayan sektör standardı olan DDEX yatar. DDEX”e neredeyse hiç doğrudan dokunmazsınız. Platform, API üzerinden oluşturduğunuz yayından bunu üretir ve sizin adınıza her DSP”ye bu dille konuşur. Her mağazayı tek tek entegre etmek yerine bir dağıtım API”si kullanmanın anlamı da budur: bir yayın modeli girer, tüm büyük DSP”lere DDEX uyumlu teslimat çıkar. LabelGrid”in dağıtım API”si, aktarımdan hesap özetlerine kadar dört aşamanın tamamını, kimlik doğrulaması yapılan tek bir yüzey altında kapsar.

Dayanacağınız endpoint”ler, bu aşamalara net biçimde karşılık gelir:

GET   /api/public/me                        # token''ı doğrula, kim olduğunu gör
GET   /api/public/releases                  # kataloğunuzu listele
POST  /api/public/releases                  # bir yayın oluştur (aktarım)
POST  /api/public/releases/{id}/validate    # bir yayını mağaza kurallarına göre kontrol et
POST  /api/public/releases/{id}/distribute  # DSP''lere teslim et
GET   /api/public/analytics                 # stream ve dinleyici verisi
GET   /api/public/statements                # telif hesap özetleri

Bu listeyi, tüm entegrasyonun iskeleti olarak düşünün. Geri kalan her şey, bu yedi çağrının üzerine asılan meta veri, yeniden denemeler ve mutabakattan ibarettir.

Kimlik Doğrulamasını Nasıl Yaparsınız?

Kimlik doğrulaması, her istekte bir bearer token ile yapılır. Kaydolur, bir API kimlik bilgisi oluşturur ve bunu Authorization başlığında gönderirsiniz. Önceden ayrılması gereken bir demo görüşmesi ya da geçilmesi gereken bir satış kapısı yoktur. Kayıt kendi kendine yapılır, dokümantasyon herkese açıktır ve bir API planı etkinleştiğinde aynı öğleden sonra kimlik doğrulamalı çağrılar yapabilirsiniz. Token”lar hesap ayarlarınızdan oluşturulur ve isteğe bağlı olarak bir token”ı bilinen IP”lerle sınırlayabilirsiniz. Yapılacak ilk çağrı GET /api/public/me”dir; bu, token”ın geçerli olduğunu ve hangi hesaba ait olduğunu size bildirir:

curl https://api.labelgrid.com/api/public/me \
  -H "Authorization: Bearer <token>"

Başka bir şey inşa etmeden önce bunun temiz bir yanıt döndürdüğünden emin olun. Çalışan bir me çağrısı, kimlik bilginizin, temel URL”nizin ve HTTP istemcinizin doğru olduğunu kanıtlar; böylece sonraki her hata, altyapıyla değil yayınla ilgili olur. Token”ı bir sır olarak saklayın, asla sürüm kontrolüne veya bir istemci paketine koymayın ve onu bir parola gibi ele alın: sızarsa döndürün, sandbox ve production için ayrı kimlik bilgileri tanımlayın ki bir test çalışması canlı kataloğa asla dokunmasın. Kesin token türü, geçerlilik süresi davranışı ve ek başlıklar API referansında belgelenmiştir; bunları tahmin etmeyin, orada bir kez okuyun ve küçük bir istemcinin içine sarın.

Bir Yayını Nasıl Oluşturur ve Teslim Edersiniz?

Bir yayını sıfırdan canlıya taşıyan üç çağrı vardır. Onu oluşturur, doğrular ve dağıtırsınız:

POST  /api/public/releases                  # 1. yayını + meta verilerini oluştur
POST  /api/public/releases/{id}/validate    # 2. mağaza kurallarına göre kontrol et
POST  /api/public/releases/{id}/distribute  # 3. DSP''lere teslim et

Mühendislik emeğinizin büyük kısmını harcayacağınız yer, oluşturma adımıdır. Bir yayın çok sayıda meta veri taşır: başlık, sanatçılar ve katkı sağlayanlar, yayın tarihi, plak şirketi, kapak görseli ve kendi başlıkları, kredileri ve sesleri olan parçalar. Kesin alanlar, formatlar ve hangilerinin zorunlu olduğu dokümantasyonda yer alır; bunları yaklaşık değil, birebir modellemelisiniz. Kötü meta veri, bir yayının sonradan başarısız olmasının en yaygın tek sebebidir, bu yüzden kendi girdilerinizi göndermeden önce doğrulayın. Kapak görseli boyutlarını kontrol edin, her parçanın bir sesi ve bir ISRC”si olduğunu teyit edin ve sanatçı isimlerini kendi tarafınızda normalleştirin; çünkü bir sorunu kendi kodunuzda yakalamak, bir mağaza reddinde yakalamaktan çok daha ucuzdur.

Oluşturmayı idempotent yapın. Ağ çağrıları yarı yolda başarısız olur ve bir yeniden denemenin aynı yayının ikinci bir kopyasını üretmesini istemezsiniz. Yeni bir yayın oluşturmadan önce bir idempotency key kullanın veya kendi referansınıza göre mevcut bir yayını kontrol edin; böylece tekrarlanan bir istek, yayını çoğaltmak yerine aynı yayını döndürür. Bu, özellikle toplu bir katalog aktarımında önemlidir; birkaç bin yayın üzerinden kesintili bir bağlantı, kesinlikle bir şeyi yeniden deneyecektir.

Teslimat asenkrondur. distribute”u çağırdığınızda, anlık bir yanıt almazsınız; bir işi kuyruğa almış olursunuz. API isteği kabul eder, ardından platform DDEX”i paketler ve arka planda her mağazaya gönderir; bu zaman alabilir. Bunu en baştan tasarlayın: distribute çağrısını gönderin, istediğinizi kaydedin, ardından bir yanıtı beklemek yerine yayının teslimat durumunu polling ile takip edin. Dağıtımın senkron tamamlandığını varsayan herhangi bir kod, gerçek bir teslimat bir saniyeden uzun sürdüğü ilk anda bozulur.

Doğrulamayı ve Hataları Nasıl Yönetirsiniz?

Doğrulamanın ayrı bir adım olmasının bir sebebi var. POST /api/public/releases/{id}/validate çağrısı, bir yayını mağaza gereksinimlerine göre kontrol eder ve teslimata geçmeden önce neyin yanlış olduğunu size geri bildirir. Dağıtmadan önce her zaman doğrulayın. Doğrulamayı geçemeyip yine de gönderilen bir yayın, bir teslimat döngüsünü boşa harcar ve daha kötüsü, baştan düzelttiğiniz bir doğrulama hatasından çok daha yavaş ve dağınık biçimde geri alınması gereken bir mağaza reddiyle sonuçlanabilir. Döngüyü oluştur, doğrula, düzelt, tekrar doğrula şeklinde kurun ve yalnızca doğrulama temiz olduğunda dağıtın.

Hata yönetiminizi sınıfa göre ayırın, çünkü iki sınıf birbirine zıt tepkiler gerektirir. Bir 4xx sizin hatanızdır: hatalı biçimlendirilmiş bir alan, eksik bir ISRC, çok küçük bir kapak görseli. Değiştirmeden yeniden denemek yalnızca tekrar başarısız olur, bu yüzden hatayı görünür kılın, veriyi düzeltin ve yeniden gönderin. Bir 5xx veya bir ağ zaman aşımı geçicidir: yeniden deneyin, ama API”yi dövmeye devam eden sıkı bir döngüyle değil, üstel geri çekilme ve bir üst sınırla. Bunu, oluşturma adımındaki idempotency key ile birleştirin ki bir zaman aşımı sonrası yeniden deneme, işi yanlışlıkla çoğaltmasın. Gerçek hata kodlarını ve anlamlarını tahmin etmek yerine dokümantasyondan okuyun ve her birini kendi sisteminizde net bir eyleme eşleyin: yeniden dene, düzelt ve yeniden gönder, ya da bir insana yükselt.

Her isteği ve yanıtı bir correlation id ile kaydedin. Üç hafta sonra bir yayın takılı kaldığında, ne gönderdiğinizin ve ne geri geldiğinin kaydı, beş dakikalık bir düzeltmeyle bir öğleden sonra boyu süren tahmin arasındaki farktır.

Telif ve Analiz Verilerini Nasıl Geri Okursunuz?

Dağıtım, döngünün yalnızca yarısıdır. Müzik yayına girdikten sonra, sisteminizin gerçeği yansıtması için performans ve kazançları geri okursunuz. Bunu iki endpoint kapsar:

GET  /api/public/analytics    # stream, dinleyici ve performans verisi
GET  /api/public/statements   # telif hesap özetleri ve kazançlar

Analiz, paneller ve kararlar içindir: stream”ler, dinleyici verisi ve bir yayının mağazalar genelinde nasıl performans gösterdiği. Hesap özetleri ise muhasebe içindir: bir dönemin gerçekte ne kazandığı, sanatçılara borçlu olduğunuz paylaşım ve ödemelerle mutabakata hazır biçimde. İkisini de bir takvime göre çekin, kendi veritabanınızda kataloğunuza bağlı olarak saklayın ve tek bir çekime güvenmek yerine mutabakat yapın. Raporlama verisi, mağazalar geç raporladıkça zamanla oturur; bu yüzden her çekimi nihai değil, en güncel görüntü olarak ele alın ve sonraki bir çekimin önceki bir tahmini düzeltmesine izin verin.

Bu yanıtların sayfalanmış olacağını bekleyin ve ilk sayfayı okuyup durmak yerine sonuna kadar sayfalayın. Güncellik için, polling ile webhook arasında ihtiyacınıza göre karar verin. Gecelik bir mutabakat işi için polling yeterlidir. Bir teslimat yayına girdiği veya bir hesap özeti geldiği anda tepki vermeniz gerekiyorsa ve webhook mevcutsa, her dakika polling yapmak yerine olaya abone olun. Her iki endpoint için kesin sorgu parametreleri, tarih aralıkları ve yanıt biçimleri API referansında yer alır; böylece tam olarak ihtiyacınız olan pencereyi çekebilirsiniz.

Production Öncesinde Sandbox”ta Nasıl Test Etmelisiniz?

Bir dağıtım entegrasyonunu asla doğrudan production”a karşı inşa etmeyin. LabelGrid, gerçek bir mağazaya hiçbir şey göndermeden oluşturma, doğrulama ve dağıtma döngüsünün tamamını çalıştırabilmeniz için tam olarak bu amaçla, genel dokümantasyonun yanında bir sandbox ortamı sunar. Entegrasyon testlerinizi ilk günden itibaren ayrı bir kimlik bilgisi kullanarak sandbox”a karşı kurun; böylece bir test çalışması, yanlışlıkla Spotify”a yarım kalmış bir yayın teslim edemez.

Yalnızca temiz bir mutlu yol değil, zorlayıcı verilerle test edin. Sandbox”a eksik ISRC”li, küçük boyutlu kapak görselli, boş sanatçı isimli ve hatalı tarihli yayınlar verin ve doğrulama-yeniden deneme mantığınızın her biriyle doğru şeyi yaptığını teyit edin. Temiz bir yayın, hattın bağlandığını kanıtlar; bozuk olanlar ise hata yönetiminizin gerçekten çalıştığını kanıtlar ve gerçek kataloglar tam da hata yönetiminde yaşar. Sandbox döngüsünü test paketinizin bir parçası yapın ki istemcinizdeki her değişiklik, yayınlanmadan önce uçtan uca sınanmış olsun.

Önce Neyi İnşa Etmelisiniz?

Geniş kapsamlı bir şey inşa etmeden önce yürüyen bir iskelet kurun. İlk kilometre taşının amacı, tüm yolu herhangi bir kısmını optimize etmeden önce kanıtlamış olmanız için sandbox”ta tek bir yayının tüm döngüden uçtan uca geçmesidir. Sırasıyla:

• Kimlik doğrulaması yapın ve GET /api/public/me”nin temiz döndüğünü görün.
• POST /api/public/releases ile gerçekçi biçimli meta verilere sahip bir yayın oluşturun.
• Doğrulayın, hataları okuyun, veriyi düzeltin ve geçene kadar doğrulamaya devam edin.
• Sandbox”ta dağıtın ve teslimat tamamlandı olarak raporlanana kadar yayını polling ile takip edin.
• Analiz ve bir hesap özetini geri okuyun ve bunları kataloğunuza karşı saklayın.

Bu iskelet yeşile döndüğünde, onu bilinçli biçimde genişletin: idempotency ile toplu katalog aktarımı, düzgün geri çekilme ve hata yönlendirmesi, zamanlanmış analiz ve hesap özeti senkronizasyonları ve daha düşük gecikme gerekiyorsa webhook”lar. Sandbox”ta tek bir yayın henüz canlıya hiç girmeden tüm katalog aktarıcısını inşa etme isteğine direnin. Zamanında teslim edilen entegrasyonlar, önce tek bir yayını baştan sona geçiren, ardından zaten çalışan deseni ölçeklendiren entegrasyonlardır.

İnşanın geri kalanının ne kadar sorunsuz gideceğini iki şey belirler. Meta veri modelinizi doğru kurmak, ki yayınlar ilk seferde doğrulamayı geçsin; ve teslimat ile raporlamayı en baştan asenkron olarak ele almak, ki kodunuzda hiçbir şey anlık bir yanıt varsaymasın. Bu ikisini doğru yaparsanız, bir dağıtım API”si entegrasyonu iyi anlaşılmış bir mühendislik problemidir. Platformları değerlendiriyorsanız, geliştirici genel bakışı ve white-label ve API dokümantasyonu, yüzeyin neyi sunduğunu kapsar; endpoint referansı ise api.labelgrid.com/docs/api adresinde herkese açıktır.

Sıkça Sorulan Sorular