Så integrerar du ett API för musikdistribution

Att integrera ett API för musikdistribution innebär att koppla ditt eget system till ett flöde som tar in en katalog, validerar dess metadata, levererar släpp till streamingplattformar och läser tillbaka royaltyer och statistik. Du skapar skivbolag, släpp och låtar via HTTP-anrop istället för ett webbformulär, skickar in varje släpp för validering, utlöser leverans till DSP:erna och hämtar sedan streams och royaltyredovisningar för att stämma av mot dina egna register. Själva anropen är den enkla delen. Det verkliga arbetet ligger i att modellera musikmetadata korrekt, hantera de asynkrona stegen och bygga för dagen då en leverans kommer tillbaka avvisad.

Den här guiden går igenom integrationen i den ordning du faktiskt skulle bygga den: autentisera, skapa och leverera ett släpp, hantera validering och fel, och läs sedan tillbaka pengarna och siffrorna. Endpoint-exemplen nedan använder LabelGrids publika API, men upplägget gäller för de flesta distributionsplattformar. Exakta fält, parametrar och felkoder finns i den publika API-dokumentationen, så det här är kartan, inte den fältvisa referensen.

Vad gör egentligen ett API för musikdistribution?

Ett distributions-API exponerar släppets livscykel som endpoints. Det finns fyra steg, och varje integration går igenom dem i samma ordning. Först katalogintag: du skapar de skivbolag, släpp och låtar som utgör din katalog och bifogar metadata och ljud. Därefter validering: du kontrollerar ett släpp mot plattformarnas regler innan det går någonstans. Därefter leverans: du distribuerar det validerade släppet till streamingtjänster och plattformar. Slutligen inläsning: du hämtar statistik och royaltyredovisningar så att ditt eget system vet vad som hände efter att musiken blev tillgänglig.

Under leveransen ligger DDEX, branschstandarden för att beskriva ett släpp och dess ljud så att en plattform kan ta emot det. Du rör nästan aldrig DDEX direkt. Plattformen genererar det utifrån släppet du byggt via API:et och talar det till varje DSP åt dig. Det är hela poängen med att använda ett distributions-API istället för att integrera mot varje plattform en och en: en släppmodell in, DDEX-kompatibel leverans till alla större DSP:er ut. LabelGrids distributions-API täcker alla fyra stegen, från intag till royaltyredovisningar, under en enda autentiserad yta.

De endpoints du kommer att luta dig mot mappar rakt av mot de här stegen:

GET   /api/public/me                        # verifiera token, se vem du är
GET   /api/public/releases                  # lista din katalog
POST  /api/public/releases                  # skapa ett släpp (intag)
POST  /api/public/releases/{id}/validate    # kontrollera ett släpp mot plattformarnas regler
POST  /api/public/releases/{id}/distribute  # leverera till DSP:erna
GET   /api/public/analytics                 # streams och lyssnardata
GET   /api/public/statements                # royaltyredovisningar

Betrakta den listan som skelettet för hela integrationen. Allt annat är metadata, omförsök och avstämning som hänger på de här sju anropen.

Hur autentiserar du dig?

Autentisering sker med en bearer-token på varje anrop. Du skapar konto, genererar en API-nyckel och skickar den i headern Authorization. Det finns inget demosamtal att boka och ingen säljspärr att ta sig förbi först. Registreringen är självbetjänad, dokumentationen är publik, och när ett API-abonnemang väl är aktivt kan du göra autentiserade anrop redan samma eftermiddag. Tokens genereras från dina kontoinställningar, och du kan valfritt begränsa en token till kända IP-adresser. Det första anropet att göra är GET /api/public/me, som talar om att token är giltig och vilket konto den tillhör:

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

Se till att den ger ett rent svar innan du bygger något annat. Ett fungerande me-anrop bevisar att din token, din bas-URL och din HTTP-klient alla är korrekta, så att ett senare fel handlar om själva släppet, inte om infrastrukturen. Förvara token som en hemlighet, aldrig i versionshantering eller en klientbundle, och behandla den som ett lösenord: rotera den om den läcker, och använd separata uppgifter för sandbox och produktion så att en testkörning aldrig kan röra en skarp katalog. Exakt tokentyp, förfallobeteende och eventuella extra headers finns dokumenterade i API-referensen; gissa inte, läs dem där en gång och paketera dem i en liten klient.

Hur skapar och levererar du ett släpp?

Tre anrop tar ett släpp hela vägen från ingenting till att vara live. Du skapar det, du validerar det och du distribuerar det:

POST  /api/public/releases                  # 1. skapa släppet + dess metadata
POST  /api/public/releases/{id}/validate    # 2. kontrollera det mot plattformarnas regler
POST  /api/public/releases/{id}/distribute  # 3. leverera det till DSP:erna

Skapandesteget är där du lägger ner mest utvecklingsarbete. Ett släpp bär på mycket metadata: titel, artister och medverkande, utgivningsdatum, skivbolag, konstverk och låtarna med sina egna titlar, krediteringar och ljud. De exakta fälten, formaten och vilka som är obligatoriska finns i dokumentationen, och du bör modellera dem exakt istället för att approximera. Dålig metadata är den vanligaste enskilda orsaken till att ett släpp misslyckas senare, så validera dina egna indata innan du någonsin skickar dem. Kontrollera konstverkets mått, bekräfta att varje låt har ljud och en ISRC, och normalisera artistnamn på din sida, eftersom det är mycket billigare att fånga ett problem i din kod än att fånga det i en avvisning från plattformen.

Gör skapandet idempotent. Nätverksanrop misslyckas halvvägs, och du vill inte att ett omförsök skapar en andra kopia av samma släpp. Använd en idempotensnyckel eller kontrollera om ett släpp redan finns via din egen referens innan du skapar ett nytt, så att en upprepad förfrågan returnerar samma släpp istället för att duplicera det. Det här spelar störst roll vid en katalogimport i bulk, där en ostabil anslutning över några tusen släpp garanterat kommer att göra om något.

Leverans är asynkron. När du anropar distribute köar du ett jobb, du får inte ett omedelbart svar. API:et tar emot förfrågan och sedan paketerar plattformen DDEX och skickar det till varje plattform i bakgrunden, vilket kan ta tid. Bygg för det från början: skicka distribute-anropet, notera att du bett om det, och polla sedan släppet för dess leveransstatus istället för att blockera på ett svar. All kod som antar att distributionen slutförs synkront kommer att gå sönder första gången en riktig leverans tar mer än en sekund.

Hur hanterar du validering och fel?

Validering är ett separat steg av en anledning. Att anropa POST /api/public/releases/{id}/validate kontrollerar ett släpp mot plattformarnas krav och ger dig tillbaka vad som är fel innan du binder dig till leverans. Validera alltid innan du distribuerar. Ett släpp som misslyckas med valideringen och ändå skickas slösar bort en leveranscykel och kan, värre än så, resultera i en avvisning hos plattformen som är långsammare och rörigare att reda ut än ett valideringsfel du åtgärdat i förväg. Bygg loopen som skapa, validera, åtgärda, validera igen, och distribuera först när valideringen är ren.

Dela upp felhanteringen efter klass, eftersom de två klasserna kräver motsatta åtgärder. En 4xx är ditt eget fel: ett felaktigt formaterat fält, en saknad ISRC, konstverk som är för litet. Att göra om samma anrop oförändrat misslyckas bara igen, så synliggör felet, fixa datan och skicka in på nytt. En 5xx eller en nätverkstimeout är övergående: gör om det, men med exponentiell backoff och ett tak, inte en tät loop som bombarderar API:et. Kombinera det med idempotensnyckeln från skapandesteget så att ett omförsök efter en timeout inte kan duplicera arbete av misstag. Läs de faktiska felkoderna och deras betydelse i dokumentationen istället för att gissa dig till dem, och koppla varje kod till en tydlig åtgärd i ditt eget system: gör om, fixa och skicka in igen, eller eskalera till en människa.

Logga varje förfrågan och svar med ett korrelations-id. När ett släpp fastnar tre veckor från nu är loggen över vad du skickade och vad som kom tillbaka skillnaden mellan en femminutersfix och en eftermiddag av gissningar.

Hur läser du tillbaka royaltyer och statistik?

Distribution är bara halva loopen. När musiken väl är tillgänglig läser du tillbaka resultat och intäkter så att ditt system speglar verkligheten. Två endpoints täcker det:

GET  /api/public/analytics    # streams, lyssnare och prestandadata
GET  /api/public/statements   # royaltyredovisningar och intäkter

Statistik är till för panelerna och besluten: streams, lyssnardata och hur ett släpp presterar över plattformarna. Royaltyredovisningar är till för bokföringen: vad en period faktiskt gav i intäkter, redo att stämmas av mot de fördelningar och utbetalningar du är skyldig artisterna. Hämta båda enligt ett schema, spara dem i din egen databas kopplat till din katalog, och stäm av istället för att lita på en enda hämtning. Rapporteringsdata sätter sig över tid eftersom plattformarna rapporterar sent, så behandla varje hämtning som den senaste bilden, inte en slutgiltig, och låt en senare hämtning korrigera en tidigare uppskattning.

Räkna med att de här svaren är paginerade, och bläddra igenom till slutet istället för att läsa den första sidan och stanna. Vad gäller aktualitet, välj mellan polling och webhooks utifrån vad du behöver. Ett nattligt avstämningsjobb klarar sig gott med polling. Om du behöver reagera i samma sekund som en leverans blir tillgänglig eller en royaltyredovisning landar, och webhooks finns tillgängliga, prenumerera på händelsen istället för att polla varje minut. De exakta query-parametrarna, datumintervallen och svarsformaten för båda endpointsen finns i API-referensen så att du kan hämta precis det fönster du behöver.

Hur bör du testa i en sandbox före produktion?

Bygg aldrig en distributionsintegration direkt mot produktion. LabelGrid tillhandahåller en sandbox-miljö tillsammans med den publika dokumentationen just så att du kan köra hela flödet med att skapa, validera och distribuera utan att skicka något till en riktig plattform. Koppla dina integrationstester mot sandboxen från dag ett, med en separat autentiseringsuppgift, så att en testkörning aldrig av misstag kan leverera ett halvfärdigt släpp till Spotify.

Testa med medvetet bristfällig data, inte bara en ren lyckad väg. Mata sandboxen med släpp som saknar ISRC, har för litet konstverk, tomma artistnamn och felaktiga datum, och bekräfta att din validerings- och omförsökslogik gör rätt med varje fall. Ett rent släpp bevisar att pipelinen fungerar, de trasiga bevisar att din felhantering faktiskt fungerar, och det är i felhanteringen som riktiga kataloger lever. Gör sandboxlivscykeln till en del av din testsvit så att varje ändring i din klient körs igenom från början till slut innan den skeppas.

Vad bör du bygga först?

Bygg ett minimalt fungerande skelett innan du bygger något brett. Målet med den första milstolpen är att ett släpp går igenom hela loopen i sandboxen, från början till slut, så att du har bevisat hela vägen innan du optimerar någon del av den. I ordning:

• Autentisera och få GET /api/public/me att returnera rent.
• Skapa ett släpp med realistiskt formad metadata via POST /api/public/releases.
• Validera det, läs felen, åtgärda datan och validera tills det går igenom.
• Distribuera det i sandboxen och polla släppet tills leveransen rapporterar klart.
• Läs tillbaka statistik och en royaltyredovisning och spara dem mot din katalog.

När det skelettet är grönt, bredda det medvetet: katalogintag i bulk med idempotens, ordentlig backoff och felroutning, schemalagd synkning av statistik och royaltyredovisningar, och webhooks om du behöver lägre latens. Stå emot lusten att bygga hela katalogimportören innan ett enda släpp någonsin blivit tillgängligt i sandboxen. De integrationer som levereras i tid är de som får ett släpp hela vägen igenom först, och sedan skalar upp mönstret som redan fungerar.

Två saker avgör hur smidig resten av bygget blir. Att få din metadatamodell rätt, så att släpp klarar valideringen första gången, och att behandla leverans och rapportering som asynkrona från början, så att inget i din kod förutsätter ett omedelbart svar. Få de två rätt, så är en integration av ett distributions-API ett välkänt tekniskt problem. Om du utvärderar plattformar täcker översikten för utvecklare och dokumentationen för white-label och API vad ytan exponerar, och endpoint-referensen är publik på api.labelgrid.com/docs/api.

Vanliga frågor