Hoe integreer je een muziekdistributie-API

Een muziekdistributie-API integreren betekent dat je je eigen systeem koppelt aan een pijplijn die een catalogus inleest, de metadata valideert, releases aanlevert aan streamingplatforms, en royalty’s en analytics terugleest. Je maakt labels, releases en tracks aan via HTTP-calls in plaats van een webformulier, dient elke release in voor validatie, start de aanlevering naar de DSP’s, en haalt vervolgens streams en overzichten op om te reconciliëren met je eigen administratie. De calls zelf zijn het makkelijke deel. Het echte werk zit in het correct modelleren van muziekmetadata, het afhandelen van de asynchrone stappen, en het bouwen voor de dag dat een aanlevering als afgewezen terugkomt.

Deze gids doorloopt die integratie in de volgorde waarin je hem daadwerkelijk zou bouwen: authenticeren, een release aanmaken en aanleveren, validatie en fouten afhandelen, en dan het geld en de cijfers teruglezen. De endpointschetsen hieronder gebruiken de publieke API van LabelGrid, maar de opzet geldt voor de meeste distributieplatforms. De exacte velden, parameters en foutcodes staan in de publieke API-documentatie, dus dit is de plattegrond, niet de veld-voor-veld-referentie.

Wat doet een muziekdistributie-API eigenlijk?

Een distributie-API stelt de levenscyclus van een release beschikbaar als endpoints. Er zijn vier fasen, en elke integratie doorloopt ze in dezelfde volgorde. Eerst catalogus inladen: je maakt de labels, releases en tracks aan die je catalogus vormen, en koppelt de metadata en audio eraan. Ten tweede validatie: je controleert een release tegen de regels van platforms voordat er iets wordt verstuurd. Ten derde aanlevering: je distribueert de gevalideerde release naar streamingdiensten en platforms. Ten vierde terugleeswerk: je haalt analytics en royaltyoverzichten op zodat je eigen systeem weet wat er is gebeurd nadat de muziek live ging.

Onder de aanlevering ligt DDEX, de industriestandaard om een release en de bijbehorende audio te beschrijven zodat een platform hem kan inlezen. Je raakt DDEX zelf bijna nooit aan. Het platform genereert het vanuit de release die je via de API hebt opgebouwd en spreekt het namens jou tegen elke DSP. Dat is het hele punt van een distributie-API gebruiken in plaats van elk platform apart te integreren: één releasemodel erin, DDEX-conforme aanlevering aan alle grote DSP’s eruit. De distributie-API van LabelGrid dekt alle vier de fasen, van inladen tot overzichten, onder één geauthenticeerd oppervlak.

De endpoints waar je op zult leunen, sluiten netjes aan op die fasen:

GET   /api/public/me                        # token controleren, zien wie je bent
GET   /api/public/releases                  # je catalogus tonen
POST  /api/public/releases                  # release aanmaken (inladen)
POST  /api/public/releases/{id}/validate    # release tegen de regels van platforms controleren
POST  /api/public/releases/{id}/distribute  # aanleveren bij de DSP's
GET   /api/public/analytics                 # streams en luisteraarsdata
GET   /api/public/statements                # royaltyoverzichten

Beschouw die lijst als het skelet van de hele integratie. Al de rest is metadata, retries en reconciliatie die aan die zeven calls hangen.

Hoe authenticeer je?

Authenticatie gebeurt met een bearer token op elk verzoek. Je registreert je, genereert een API-credential en stuurt die mee in de Authorization-header. Er is geen demo-call te boeken en geen salesgate om eerst langs te komen. Registreren is self-service, de documentatie is publiek, en zodra een API-abonnement actief is, kun je dezelfde middag nog geauthenticeerde calls doen. Tokens genereer je vanuit je accountinstellingen, en je kunt een token optioneel beperken tot bekende IP-adressen. De eerste call die je doet is GET /api/public/me, die je vertelt of het token geldig is en bij welk account het hoort:

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

Zorg dat die een schone response teruggeeft voordat je iets anders bouwt. Een werkende me-call bewijst dat je credential, je base-URL en je HTTP-client allemaal kloppen, zodat elke latere fout over de release gaat en niet over de leidingen. Bewaar het token als een secret, nooit in versiebeheer of een clientbundel, en behandel het als een wachtwoord: roteer het als het lekt, en gebruik gescheiden credentials voor sandbox en productie zodat een testrun nooit de live catalogus kan raken. Het exacte tokentype, het verloopgedrag en eventuele extra headers staan gedocumenteerd in de API-referentie; gok er niet naar, lees ze daar eenmalig en wikkel ze in een kleine client.

Hoe maak je een release aan en lever je hem aan?

Drie calls brengen een release van niets naar live. Je maakt hem aan, je valideert hem, en je distribueert hem:

POST  /api/public/releases                  # 1. release + metadata aanmaken
POST  /api/public/releases/{id}/validate    # 2. tegen de regels van platforms controleren
POST  /api/public/releases/{id}/distribute  # 3. aanleveren bij de DSP's

De aanmaakstap is waar je het meeste engineeringwerk in stopt. Een release draagt veel metadata: titel, artiesten en medewerkers, releasedatum, label, artwork, en de tracks met hun eigen titels, credits en audio. De precieze velden, formaten en welke daarvan verplicht zijn, staan allemaal in de documentatie, en je moet ze exact modelleren in plaats van benaderen. Slechte metadata is de meest voorkomende reden waarom een release later faalt, dus valideer je eigen input voordat je die ooit verstuurt. Controleer de afmetingen van het artwork, bevestig dat elke track audio en een ISRC heeft, en normaliseer artiestennamen aan jouw kant, want een probleem opvangen in je eigen code is veel goedkoper dan het opvangen in een afwijzing door een platform.

Maak het aanmaken idempotent. Netwerkcalls falen halverwege, en je wilt niet dat een retry een tweede kopie van dezelfde release oplevert. Gebruik een idempotency key of controleer op een bestaande release aan de hand van je eigen referentie voordat je een nieuwe aanmaakt, zodat een herhaald verzoek dezelfde release teruggeeft in plaats van hem te dupliceren. Dit speelt het sterkst bij een bulk-catalogusimport, waar een wankele verbinding over een paar duizend releases gegarandeerd ergens een retry uitlokt.

Aanlevering is asynchroon. Wanneer je distribute aanroept, zet je een taak in de wachtrij, je krijgt geen direct antwoord. De API accepteert het verzoek en dan pakt het platform DDEX in en verstuurt het op de achtergrond naar elk platform, wat tijd kan kosten. Ontwerp daar vanaf het begin voor: vuur de distribute-call af, leg vast dat je het hebt aangevraagd, en poll daarna de release voor de aanleverstatus in plaats van te wachten op een response. Alle code die ervan uitgaat dat distributie synchroon voltooit, breekt de eerste keer dat een echte aanlevering langer dan een seconde duurt.

Hoe ga je om met validatie en fouten?

Validatie is niet voor niets een aparte stap. Het aanroepen van POST /api/public/releases/{id}/validate controleert een release tegen de eisen van platforms en geeft je terug wat er mis is voordat je je vastlegt op aanlevering. Valideer altijd voordat je distribueert. Een release die validatie niet doorstaat en toch wordt verstuurd, verspilt een aanlevercyclus en kan erger nog leiden tot een afwijzing bij het platform, die trager en rommeliger is om terug te draaien dan een validatiefout die je vooraf hebt opgelost. Bouw de lus als aanmaken, valideren, fixen, opnieuw valideren, en distribueer pas zodra validatie schoon is.

Splits je foutafhandeling per klasse, want de twee klassen vragen om tegenovergestelde reacties. Een 4xx is jouw fout: een misvormd veld, een ontbrekende ISRC, artwork dat te klein is. Onveranderd opnieuw proberen faalt gewoon weer, dus maak het zichtbaar, fix de data en dien opnieuw in. Een 5xx of een netwerktime-out is tijdelijk: probeer het opnieuw, maar met exponentiële backoff en een limiet, geen strakke lus die de API bestookt. Combineer dat met de idempotency key uit de aanmaakstap, zodat een retry na een time-out nooit per ongeluk werk dupliceert. Lees de daadwerkelijke foutcodes en hun betekenis in de documentatie in plaats van ze af te leiden, en koppel elke code aan een duidelijke actie in je eigen systeem: opnieuw proberen, fixen en opnieuw indienen, of escaleren naar een mens.

Log elk verzoek en elke response met een correlation id. Als een release over drie weken vastzit, maakt de log van wat je hebt verstuurd en wat er terugkwam het verschil tussen een fix van vijf minuten en een middag lang gissen.

Hoe lees je royalty’s en analytics terug?

Distributie is maar de helft van de cirkel. Zodra muziek live staat, lees je prestaties en inkomsten terug zodat je systeem de werkelijkheid weerspiegelt. Twee endpoints dekken dat:

GET  /api/public/analytics    # streams, luisteraars en prestatiedata
GET  /api/public/statements   # royaltyoverzichten en inkomsten

Analytics is voor de dashboards en beslissingen: streams, luisteraarsdata en hoe een release presteert over de platforms heen. Overzichten zijn voor de boekhouding: wat een periode daadwerkelijk heeft opgebracht, klaar om te reconciliëren met de splits en uitbetalingen die je artiesten verschuldigd bent. Haal beide op een schema op, sla ze op in je eigen database gekoppeld aan je catalogus, en reconcilieer in plaats van te vertrouwen op één enkele ophaling. Rapportagedata zet zich in de loop van de tijd, omdat platforms met vertraging rapporteren, dus behandel elke ophaling als het meest actuele beeld, niet als definitief, en laat een latere ophaling een eerdere schatting corrigeren.

Verwacht dat deze responses gepagineerd zijn, en blader ze volledig door in plaats van alleen de eerste pagina te lezen en te stoppen. Voor actualiteit kies je tussen pollen en webhooks op basis van wat je nodig hebt. Een nachtelijke reconciliatietaak is prima op een poll. Als je moet reageren op het moment dat een aanlevering live gaat of een overzicht binnenkomt, en webhooks beschikbaar zijn, abonneer je dan op het event in plaats van elke minuut te pollen. De exacte queryparameters, datumbereiken en responsestructuren voor beide endpoints staan in de API-referentie, zodat je precies het venster kunt ophalen dat je nodig hebt.

Hoe test je in een sandbox voordat je naar productie gaat?

Bouw een distributie-integratie nooit rechtstreeks tegen productie. LabelGrid biedt een sandboxomgeving naast de publieke documentatie, precies zodat je de volledige levenscyclus van aanmaken, valideren en distribueren kunt doorlopen zonder iets naar een echt platform te sturen. Koppel je integratietests vanaf dag één aan de sandbox, met een aparte credential, zodat een testrun nooit per ongeluk een halfafgemaakte release aan Spotify aanlevert.

Test met adversariële data, niet alleen met een schoon happy path. Voer de sandbox releases met ontbrekende ISRC’s, te kleine artwork, lege artiestennamen en foute datums, en bevestig dat je validatie- en retrylogica bij elk daarvan het juiste doet. Een schone release bewijst dat de pijplijn verbindt; de kapotte exemplaren bewijzen dat je foutafhandeling echt werkt, en foutafhandeling is waar echte catalogi leven. Maak de sandboxcyclus onderdeel van je testsuite, zodat elke wijziging aan je client end-to-end wordt getest voordat die live gaat.

Wat bouw je eerst?

Bouw eerst een walking skeleton voordat je iets breed uitbouwt. Het doel van de eerste mijlpaal is één release die de hele cirkel in de sandbox doorloopt, van begin tot eind, zodat je het hele pad hebt bewezen voordat je enig onderdeel ervan optimaliseert. In volgorde:

• Authenticeer en zorg dat GET /api/public/me schoon teruggeeft.
• Maak één release aan met realistisch gevormde metadata via POST /api/public/releases.
• Valideer hem, lees de fouten, fix de data, en valideer opnieuw tot hij slaagt.
• Distribueer hem in de sandbox en poll de release tot de aanlevering compleet meldt.
• Lees analytics en een overzicht terug en sla ze op tegen je catalogus.

Zodra dat skelet groen is, breid je het bewust uit: bulk-catalogusinlading met idempotency, degelijke backoff en foutroutering, geplande synchronisaties van analytics en overzichten, en webhooks als je lagere latency nodig hebt. Weersta de drang om de hele catalogusimporter te bouwen voordat er ooit één release live is gegaan in de sandbox. De integraties die op tijd live gaan, zijn de integraties die eerst één release helemaal door de cirkel krijgen, en pas daarna het patroon opschalen dat al werkt.

Twee dingen bepalen hoe soepel de rest van de bouw verloopt. Je metadatamodel goed krijgen, zodat releases de eerste keer door validatie komen, en aanlevering en rapportage vanaf het begin als asynchroon behandelen, zodat niets in je code uitgaat van een direct antwoord. Krijg die twee goed voor elkaar en een integratie met een distributie-API is een goed te doorgronden engineeringprobleem. Als je platforms aan het evalueren bent, dekken het overzicht voor developers en de documentatie over white-label en API wat het oppervlak blootstelt, en de endpointreferentie is publiek beschikbaar op api.labelgrid.com/docs/api.

Veelgestelde vragen