Nieuwe functie: de Cyql API

Clubs gebruiken Cyql al voor hun ritten, leden en communicatie. Maar een groeiende groep technisch onderlegde clubs en ontwikkelaars stelde ons steeds vaker dezelfde vraag:

“Kunnen we onze clubdata ook buiten het dashboard gebruiken?”
“We willen ritten tonen op onze eigen website.”
“We bouwen een eigen ledenportaal — kunnen we data ophalen?”
“We willen Cyql koppelen aan onze eigen systemen.”

Vandaag is dat mogelijk. We introduceren de Cyql API.

Gebouwd op basis van feedback van clubs

Sommige clubs zijn technisch genoeg om zelf tools te bouwen. Ze willen de data die al in Cyql zit, niet opnieuw invoeren in een ander systeem. Andere clubs werken samen met een developer of webbeheerder die hun site up-to-date wil houden zonder dat er handmatig werk aan te pas komt.

De Cyql API maakt dat allemaal mogelijk — zonder dat je afhankelijk bent van wat het dashboard standaard toont.

Een GraphQL API: flexibel en efficiënt

De Cyql API is gebouwd op GraphQL. Dat betekent dat je precies opvraagt wat je nodig hebt — niet meer, niet minder. Geen vaste endpoints met data die je toch niet gebruikt. Jij bepaalt de structuur van je response.

Alle verzoeken gaan via één endpoint:

POST /api/graphql
Host: api.cyql.app
Content-Type: application/json
X-Api-Key: jouw-api-sleutel

Een eenvoudig voorbeeld om het aantal leden op te halen:

query {
  clubStats {
    memberCount
  }
}

De response is altijd overzichtelijke JSON:

{
  "data": {
    "clubStats": {
      "memberCount": 147
    }
  }
}

Wat kun je opvragen?

De API geeft je toegang tot alle relevante clubdata:

• Ritten — Haal geplande en afgelopen ritten op, inclusief afstand, hoogtemeters, startlocatie, gemiddeld tempo en rittype. Ideaal om een ritoverzicht op je clubwebsite te tonen.
• Leden — Raadpleeg ledenprofielen met naam, e-mail, lidmaatschapsstatus en rol binnen de club. Handig voor ledenportalen of interne dashboards.
• Statistieken — Totaal aantal ritten, actieve leden, gereden kilometers en het aantal beheerders — een live snapshot van je club.
• Clubinformatie — Naam, stad, omschrijving en contactgegevens van de club.
• Nieuws — Nieuwsartikelen met publicatiedatum, afbeelding en bijlagen.
• Evenementen — Agenda-items met datum, locatie en bijbehorende documenten.
• GPX-routes — Routebibliotheek met afstand, hoogtemeters, downloadlink en routelabels.
• Uitdagingen — Actieve challenges met deelnemersaantallen, scoringstype en ranglijsten.

Authenticatie en veiligheid

API-sleutels maak je aan in het Cyql-dashboard onder Instellingen → API. Elke sleutel geef je mee als header bij je verzoek:

X-Api-Key: jouw-api-sleutel

Er zijn geen gedeelde wachtwoorden, geen ingewikkelde OAuth-flows. Eén sleutel, en je bent aan de slag.

Rate limiting: eerlijk gebruik voor iedereen

Om het platform stabiel te houden voor alle clubs, werkt de API met een wekelijks limiet per sleutel. Die limiet reset elke maandag om 00:00 UTC. Elke response bevat handige headers zodat je altijd weet waar je staat:

• X-RateLimit-Limit — het maximale aantal verzoeken per week voor deze sleutel
• X-RateLimit-Remaining — hoeveel verzoeken er nog over zijn
• X-RateLimit-Remaining-Club — het gezamenlijke restant voor alle sleutels van de club
• X-RateLimit-Reset — wanneer de teller opnieuw begint

Heb je meerdere toepassingen? Maak dan meerdere sleutels aan — zo kun je per gebruik de limieten beheren.

Query complexity: slim omgaan met resources

GraphQL is flexibel, maar sommige queries vragen meer van de server dan andere. Daarom werkt de Cyql API met een complexity budget: elke query krijgt een score op basis van het aantal velden en de paginagrootte die je opvraagt.

Praktische tip: vraag alleen de velden op die je écht nodig hebt. In plaats van alle velden van een rit op te halen, vraag je alleen title, startTime en distance als dat voldoende is. Kleinere queries zijn sneller, goedkoper en vriendelijker voor je budget.

Paginering ingebouwd

Elke lijst-query — van ritten tot leden tot nieuws — ondersteunt paginering uit de doos. De response bevat altijd:

• items — de resultaten voor de huidige pagina
• totalCount — het totale aantal items
• page en pageSize — de huidige positie
• hasNextPage — of er nog meer data beschikbaar is

Zo bouw je eenvoudig een volledige lijst op, stap voor stap.

Aan de slag

API-sleutels zijn beschikbaar in het Cyql-dashboard. Heb je een ontwikkelaar die je clubwebsite beheert? Stuur hem of haar naar de API-documentatie op api.cyql.app/docs — daar staat een interactieve query builder waarmee je queries kunt samenstellen en direct testen.

Zoals altijd is deze functie er omdat clubs erom vroegen. En we blijven hem verder uitbreiden op basis van wat jullie ermee bouwen.

Veel fietsplezier 🚴‍♂️