Datenaustausch

Parkour Design stellt derzeit einen abgestimmten, schreibgeschützten Ressourcendienst für Zusammenfassungen von Veranstaltungen und Parcoursentwürfen bereit. Vollständige Projektgeometrie, Dateien, Schreibvorgänge und Synchronisierung erfordern einen separaten Partnervertrag.

Vertragsstatus: Die folgenden Endpunkte beschreiben das aktuell bereitgestellte Verhalten für genehmigte Clients. Sie stellen noch keine versionierte allgemeine API dar. Entwickeln Sie erst gegen diese Endpunkte, nachdem Parkour Design Zugriff, Scopes, Limits und den Vertrag für die Inbetriebnahme bestätigt hat.

Basis-URL und Authentifizierung

Verwenden Sie den für die OAuth-Umgebung ausgewählten Issuer als API-Basis-URL:

Senden Sie das Zugriffstoken von Parkour Design aus einem Backend-Dienst:

Authorization: Bearer <access_token>
Accept: application/json

Das Zugriffstoken muss für den konfigurierten Issuer und die Audience parkour-api gültig sein, für token_use den Wert access_token aufweisen und derzeit openid enthalten.

Die API unterstützt derzeit keinen Cross-Origin-Zugriff aus Browsern. Legen Sie das Zugriffs- oder Refresh-Token nicht gegenüber dem JavaScript des Frontends offen.

Veranstaltungen auflisten

GET /api/events

Beispielanfrage:

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

Beispielantwort:

{
  "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
    }
  ]
}

Aktueller Antworttyp:

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

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

Veranstaltungen werden aus den nicht gelöschten Entwürfen des authentifizierten Benutzers zusammengestellt. Entwürfe ohne Veranstaltungsidentifikator werden ausgelassen.

Behandeln Sie id als undurchsichtigen Wert. Übernehmen Sie ihn unverändert in die Anfrage für Entwurfszusammenfassungen. Leiten Sie sein Format nicht ab und erzeugen Sie ihn nicht im Partnersystem.

Entwurfszusammenfassungen für eine Veranstaltung auflisten

GET /api/events/{eventId}/designs

Beispielanfrage:

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

Beispielantwort:

{
  "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"
    }
  ]
}

Aktueller Antworttyp:

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[];
};

Datumsangaben sind, sofern vorhanden, ISO-8601-Zeichenfolgen in UTC. Clients müssen null für optionale Datumsangaben und localId unterstützen.

Eigentum und Sichtbarkeit

Der sub-Claim des Bearer-Tokens identifiziert den Eigentümer der Ressourcen von Parkour Design. Antworten enthalten ausschließlich nicht gelöschte Entwürfe, die diesem Benutzer gehören.

Der aktuelle Dienst bietet keinen Zugriff auf:

• Ressourcen der gesamten Organisation oder des gesamten Teams;
• freigegebene oder öffentliche Entwürfe eines anderen Benutzers;
• Client-spezifische Ressourcenfilterung;
• gelöschte Entwürfe;
• Abonnement-, Profil- oder Zahlungsdaten.

Sowohl eine nicht vorhandene Veranstaltung als auch eine Veranstaltung im Eigentum eines anderen Benutzers geben 404 zurück. Verwenden Sie diese Antwort nicht, um abzuleiten, ob die Ressource eines anderen Benutzers vorhanden ist.

Aktuelle Limits und Sortierung

Die aktuellen Endpunkte akzeptieren keine Parameter für Filterung, Sortierung, Paginierung, Cursor oder inkrementelle Synchronisierung.

• /api/events gibt die zusammengestellte Liste der Veranstaltungen in einer Antwort zurück.
• /api/events/{eventId}/designs gibt höchstens 500 Zusammenfassungen zurück.
• Die Antwort weist derzeit weder auf eine Kürzung hin noch stellt sie einen Fortsetzungscursor bereit.
• Die Sortierung entspricht dem Verhalten der aktuellen Implementierung und ist noch keine versionierte Garantie.

Bevor eine Integration für den Produktivbetrieb genehmigt wird, müssen Parkour Design und der Partner bestätigen, dass das erwartete Datenvolumen innerhalb dieser Limits liegt. Ein Partner, der eine vollständige Paginierung oder inkrementelle Aktualisierungen benötigt, darf dies nicht durch Scraping oder das Erraten von Identifikatoren umgehen; hierfür ist ein überarbeiteter Vertrag erforderlich.

Fehlerantworten

Fehler verwenden einen kompakten JSON-Body:

{"error": "not_found"}

Unerwartete Dienstausfälle verfügen noch nicht über ein separat versioniertes Fehlerschema. Clients sollten andere 5xx-Antworten nur bei idempotenten GET-Vorgängen als wiederholbar behandeln und dabei einen begrenzten exponentiellen Backoff mit Jitter verwenden.

Von dieser API nicht bereitgestellte Daten

Die Entwurfszusammenfassung ist kein vollständiger Parcoursentwurf. Die aktuelle Ressourcen-API stellt Folgendes nicht bereit:

• Parcoursgeometrie oder Streckenführung;
• Hindernisse, Gruppen, Aufbau des Turnierplatzes oder Zeichenobjekte;
• generierte PDF-Dateien, Vorschauen, Bilder oder Download-URLs;
• Vorgänge zum Erstellen, Aktualisieren, Löschen oder Hochladen;
• Abruf eines einzelnen Entwurfs anhand seiner Entwurfs-ID;
• Webhooks oder einen Änderungsfeed;
• Eqify-Zugriffstokens, Sitzungen, Wettkämpfe, Aktivitäten oder gespeicherte Ziele.

Stellen Sie eine Zusammenfassungsantwort nicht als druckbaren oder bearbeitbaren Parcoursentwurf dar.