Een ander systeem koppelen met de API
Maak een sleutel en laat je website, app of schermen gegevens uit Airly ophalen. In de documentatie staat elk endpoint, en je kunt het meteen uitproberen.
/settings/apiMet de API haalt een ander systeem gegevens uit Airly. Denk aan je website die de programmagids toont, of een scherm in het gebouw dat laat zien wat er nu op de radio is. Zo’n systeem heeft een sleutel nodig.
Je vindt alles bij Instellingen › API. Daar staan twee tabbladen: Sleutels en Documentatie. Alleen beheerders zien ze.
Een sleutel maken#
- Ga naar Instellingen › API, tabblad Sleutels.
- Kies Nieuwe sleutel en geef hem een naam, zoals “Programmagids op de website”.
- Zet alleen aan wat de sleutel nodig heeft. Per onderdeel kies je Lezen en Schrijven.
- Kies hoe lang hij werkt: 3 maanden, 1 jaar of 2 jaar.
- Kopieer de sleutel en bewaar hem op een veilige plek. Je ziet hem maar één keer.
Grote onderdelen zijn in stukken verdeeld. Zo geef je een sleutel alleen wat hij nodig heeft:
- Hitlijsten: de hitlijsten en uitslagen, de Stemmen (met naam, e-mail en telefoon) en de Muzieklijsten.
- Prijswinnaars: de Winnaars (met adres) en de Prijzen en regels.
- Verhalen: de verhalen en artikelen, de Radio-items, de Taken en de Weekplanning.
- Commercials: de adverteerders en campagnes, de Spots en blokken en de Tarieven.
- Programmagids: de Gids, de Standaardweek en de Playout-import.
- Draaiboeken: de draaiboeken en de Draaiboekschema’s.
- Reserveren: de Reserveringen en de Inrichting (soorten, items en instellingen).
- Contacten: de contacten en de Contactmomenten.
Staat er een streepje in plaats van een schakelaar? Dan kan dat niet via de API. De playout-import kan bijvoorbeeld alleen schrijven.
Kwijt? Trek de sleutel in en maak een nieuwe. Bijna verlopen? Kies Een jaar verlengen in het menu achter de sleutel. Twee weken voordat een sleutel stopt, krijgen alle beheerders een melding en een mail. Die mail zet je aan of uit bij Instellingen › E-mails.
Wat een koppeling met een sleutel schrijft, doet Airly namens de beheerder die de sleutel maakte. Je ziet het terug in het Zien wie wat heeft gedaan in het audit log.
De documentatie#
Op het tabblad Documentatie staat hoe de API werkt. Links staat het menu, op dezelfde plek als het menu van Instellingen. Met Instellingen bovenaan ga je terug.
- Aan de slag legt uit hoe je een sleutel meestuurt, hoe fouten eruitzien en hoe de limiet werkt.
- Endpoints staan per onderdeel, zoals Programmagids (De programmagids bekijken en aanpassen), Reserveren (Een studio, materiaal of auto reserveren) of Agenda (De agenda van je redactie gebruiken). Klik op een onderdeel om zijn endpoints te zien. Met het zoekveld zoek je op een pad, zoals
/epg. - Schema’s laat de velden zien van wat de API teruggeeft.
Klik op een endpoint om het open te klappen. Je ziet dan:
- welk recht de sleutel nodig heeft (bij het slotje),
- welke parameters en velden je meestuurt,
- een voorbeeld in cURL, JavaScript, PHP of Python,
- de antwoorden per statuscode. Bij een aantal endpoints staat een echt voorbeeld.
De lijst met endpoints komt rechtstreeks uit Airly. Komt er iets bij, dan staat het er meteen in.
Probeer het uit#
Je kunt een endpoint meteen proberen, met je eigen sleutel.
- Klap het endpoint open en kies Probeer het uit.
- Vul de parameters in. De eerste zender staat al ingevuld.
- Plak je sleutel. Je ziet alleen puntjes; met het oogje zie je hem.
- Kies Uitvoeren. Je ziet het adres, de status, hoe lang het duurde en het antwoord.
Je sleutel blijft alleen in dit venster. Airly bewaart hem niet. Herlaad je de pagina, dan is hij weg.
Goed om te weten#
- Je omroep mag 250 verzoeken per minuut doen, met alle sleutels samen.
- De API zelf hoort bij jullie abonnement. Staat hij uit, dan zie je API niet bij Instellingen en werkt geen enkele sleutel. Vraag Airly om hem aan te zetten.
- Zit een onderdeel niet in jullie abonnement, dan werkt de sleutel daar niet. Ook niet met het goede recht.
- AI-functies en koppelingen, zoals Microsoft 365 of een mailbox, kunnen niet via de API.
- Zet een sleutel nooit in code die in de browser van bezoekers draait. Alleen Appjes in beeld is daarvoor bedoeld. Lees daarover Appjes in beeld tonen.
- Het oude adres van de documentatie (
/api-docs) brengt je vanzelf naar de nieuwe plek.