Uw tools verbinden met de API
Met de API kan een externe applicatie programmatisch toegang krijgen tot de gegevens van uw club: ledenbestand, kalenders, boekingen en facturatie. U activeert deze in twee klikken en beveiligt deze met een sleutel, een lijst met toegestane adressen en verbruiksopvolging.
Weten of de API voor u bedoeld is
De API is bedoeld voor een ontwikkelaar, niet voor een clubbeheerder. Ze dient om uw account te laten communiceren met software die u laat schrijven of configureren: een website op maat, een boekhoudtool, een eigen weergavescherm, een koppeling naar een ander systeem.
Voor courante behoeften — de ledenlijst ophalen, abonnementen in bulk bijwerken, cijfers doorgeven aan het bestuur — voldoen de modules voor import, export en rapporten zonder één regel code te schrijven.
De API wordt aangeboden in bètaversie: de werking kan nog veranderen.
De API activeren en uw sleutel ophalen
- Ga naar Administratie›Instellingen›API BETA.
- Activeer API-module activeren en klik daarna op Opslaan.
- Uw API-sleutel verschijnt: kopieer deze met de knop Kopiëren en geef deze alleen door aan de tool die u verbindt.
De sleutel wordt meegestuurd in de HTTP-header X-API-Key van elk verzoek. Aanroepen moeten verplicht via HTTPS verlopen. Onversleutelde verzoeken worden niet geaccepteerd.
De sleutel beschermen
Wijs de tool of de dienstverlener die de sleutel gebruikt op enkele belangrijke gewoonten:
- plaats de sleutel nooit in een code-repository; sla deze op in een configuratiebestand buiten de repository of in een geheimenbeheerder;
- beperk de toegestane adressen zodra de tool aanroept vanaf een vaste server;
- genereer de sleutel opnieuw bij de minste twijfel — onbedoelde publicatie, lek in logbestanden, einde van de opdracht van een dienstverlener.
De knop Regenereren vraagt om bevestiging en maakt de oude sleutel daarna onmiddellijk ongeldig. Alle applicaties die deze gebruikten, werken niet meer totdat ze de nieuwe sleutel hebben ontvangen: waarschuw ze voordat u klikt.
Toegang beperken op IP-adres
Activeer de Beperking op IP-adres: alleen verzoeken vanaf de adressen die u opgeeft, worden geaccepteerd, met een maximum van 10 IPv4-adressen. Voer elk adres in en bevestig met Toevoegen. Uw huidige adres wordt op het scherm weergegeven om u te helpen.
Dit is de meest effectieve bescherming en ook de bescherming die het vaakst wordt vergeten: zelfs als een sleutel wordt gelekt, blijft een sleutel die beperkt is tot het adres van uw dienstverlener elders onbruikbaar.
Het verbruik volgen
Het scherm toont continu wat uw sleutel verbruikt:
- Gebruik deze minuut en Gebruik vandaag, elk afgezet tegen de limiet wanneer er een limiet is geconfigureerd;
- Gebruiksstatistieken: Deze week, Deze maand, Totaal en Laatste verzoek.
Boven de aangegeven limieten worden extra verzoeken tijdelijk geweigerd. Een teller die voortdurend dicht bij zijn maximum zit, wijst meestal op een verkeerd ingestelde tool die telkens dezelfde gegevens opnieuw opvraagt in plaats van ze in de cache op te slaan.
De datum van het laatste verzoek is ook in de omgekeerde richting nuttig: een geactiveerde sleutel die al maanden nooit is aangeroepen, is een sleutel die u moet deactiveren.
Ontdekken wat de API mogelijk maakt
De volledige documentatie, met parameters en voorbeelden van aanroepen, wordt onderaan het scherm van de module weergegeven. In hoofdlijnen:
- Gebruikers: dit is de enige resource die kan worden gewijzigd. U kunt accounts oplijsten, raadplegen, aanmaken, wijzigen en verwijderen.
- Configuratie: abonnementen, profielen, groepen en leeftijdscategorieën kunnen worden geraadpleegd, maar alleen vanuit de applicatie worden geconfigureerd.
- Boekingen: kalenders, beschikbare tijdsloten, boekingen en blokkeringslabels kunnen worden geraadpleegd.
- Facturatie: facturatieaccounts, bestellingen en betalingen kunnen worden geraadpleegd.
