Menu van de documentatie
Per partner Laatst bijgewerkt: 27 juli 2026

Gegevensuitwisseling

Gebruik de huidige alleen-lezen resources voor partners en leg een veilig contract vast voor de uitwisseling van parcoursontwerpen per partner.

Parkour Design biedt nu een afgestemde, alleen-lezen resourcedienst voor overzichten van evenementen en parcoursontwerpen. Voor de volledige geometrie van projecten, bestanden, schrijfacties en synchronisatie is een apart partnercontract nodig.

Status van het contract: De endpoints hieronder beschrijven het huidige gedrag in productie voor goedgekeurde clients. Ze zijn nog geen geversioneerde algemene API. Bouw er niet op voordat Parkour Design de toegang, scopes, limieten en het lanceringscontract heeft bevestigd.

Basis-URL en authenticatie

Gebruik de issuer van de gekozen OAuth-omgeving als basis-URL van de API:

OmgevingBasis-URL
Productiehttps://app.parkour.design
Testhttps://parkour-test.web.app

Stuur het toegangstoken van Parkour Design vanuit een backenddienst:

Authorization: Bearer <access_token>
Accept: application/json

Het toegangstoken moet geldig zijn voor de ingestelde issuer en de audience parkour-api, token_use gelijk aan access_token hebben en nu openid bevatten.

De API biedt nu geen cross-origin toegang vanuit de browser. Geef het toegangstoken of refresh token nooit aan JavaScript in de frontend.

Evenementen opvragen

GET /api/events

Voorbeeldverzoek:

curl "${ISSUER}/api/events" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

Voorbeeldantwoord:

{
  "items": [
    {
      "id": "abcdefghijklmnopqrstuv",
      "name": "Example Event",
      "startDate": "2026-07-24T00:00:00Z",
      "endDate": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T18:42:10Z",
      "designCount": 4
    }
  ]
}

Huidig antwoordtype:

type EventSummary = {
  id: string;
  name: string;
  startDate: string | null;
  endDate: string | null;
  updatedAt: string | null;
  designCount: number;
};

type EventsResponse = {
  items: EventSummary[];
};

Evenementen worden samengesteld uit de niet-verwijderde ontwerpen van de ingelogde gebruiker. Ontwerpen zonder evenement worden weggelaten.

Behandel id als ondoorzichtig. Neem de waarde ongewijzigd over in het verzoek om ontwerpoverzichten. Leid het formaat niet af en genereer het niet in het systeem van de partner.

Ontwerpoverzichten van een evenement opvragen

GET /api/events/{eventId}/designs

Voorbeeldverzoek:

curl "${ISSUER}/api/events/${EVENT_ID}/designs" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

Voorbeeldantwoord:

{
  "event": {
    "id": "abcdefghijklmnopqrstuv",
    "name": "Example Event",
    "startDate": "2026-07-24T00:00:00Z",
    "endDate": "2026-07-26T00:00:00Z",
    "updatedAt": "2026-07-26T18:42:10Z",
    "designCount": 4
  },
  "items": [
    {
      "id": "design-record-id",
      "localId": "design-local-id",
      "eventId": "abcdefghijklmnopqrstuv",
      "title": "Grand Prix",
      "eventName": "Example Event",
      "eventDate": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T18:42:10Z",
      "authorName": "Course Designer",
      "shortDescr": "Competition description"
    }
  ]
}

Huidig antwoordtype:

type DesignSummary = {
  id: string;
  localId: string | null;
  eventId: string;
  title: string;
  eventName: string;
  eventDate: string | null;
  updatedAt: string | null;
  authorName: string | null;
  shortDescr: string;
};

type EventDesignsResponse = {
  event: EventSummary;
  items: DesignSummary[];
};

Datums zijn ISO 8601-strings in UTC, als ze aanwezig zijn. Clients moeten null ondersteunen voor optionele datums en localId.

Eigendom en zichtbaarheid

De sub van het bearer-token geeft de eigenaar van de resources in Parkour Design aan. Antwoorden bevatten alleen niet-verwijderde ontwerpen van die gebruiker.

De huidige dienst biedt geen:

  • toegang voor een hele organisatie of een team;
  • toegang tot gedeelde of openbare ontwerpen van een andere gebruiker;
  • filtering van resources per client;
  • verwijderde ontwerpen;
  • gegevens over abonnement, profiel of betalingen.

Een niet-bestaand evenement en een evenement van een andere gebruiker geven allebei 404. Gebruik dit antwoord niet om af te leiden of een resource van een andere gebruiker bestaat.

Huidige limieten en volgorde

De huidige endpoints accepteren geen parameters voor filteren, sorteren, paginering, cursors of incrementele synchronisatie.

  • /api/events geeft de samengestelde lijst met evenementen in één antwoord.
  • /api/events/{eventId}/designs geeft maximaal 500 overzichten.
  • Het antwoord geeft nu niet aan of het is afgekapt en bevat geen vervolgcursor.
  • De volgorde is huidig gedrag van de implementatie en nog geen geversioneerde garantie.

Voor de goedkeuring van een productie-integratie moeten Parkour Design en de partner bevestigen dat het verwachte datavolume binnen deze limieten past. Een partner die volledige paginering of incrementele updates nodig heeft, mag dat niet oplossen door te scrapen of identificaties te raden; daarvoor is een herzien contract nodig.

Foutantwoorden

Fouten gebruiken een compacte JSON-body:

{"error": "not_found"}
StatusFoutBetekenis
401invalid_tokenOntbrekend, onjuist opgebouwd, verlopen, ongeldig of nu onvoldoende afgebakend bearer-token
404not_foundOngeldige route of evenement niet beschikbaar voor deze gebruiker
405method_not_allowedAndere methode dan GET

Onverwachte storingen van de dienst hebben nog geen apart geversioneerd foutschema. Clients mogen andere 5xx-antwoorden alleen bij idempotente GET-verzoeken opnieuw proberen, met een begrensde exponentiële backoff en jitter.

Gegevens die deze API niet levert

Het ontwerpoverzicht is geen volledig parcoursontwerp. De huidige resource-API levert geen:

  • geometrie of route van het parcours;
  • hindernissen, groepen, opstelling van de piste of tekenobjecten;
  • gegenereerde PDF’s, voorbeelden, afbeeldingen of download-URL’s;
  • bewerkingen voor maken, wijzigen, verwijderen of uploaden;
  • opvraging van één ontwerp op basis van zijn ontwerp-ID;
  • webhooks of een wijzigingsfeed;
  • toegangstokens, sessies, rubrieken, activiteiten of opgeslagen bestemmingen van Eqify.

Presenteer een overzichtsantwoord niet als afdrukbaar of bewerkbaar parcoursontwerp.