Parkour Design gestisce attualmente un servizio di risorse coordinato, in sola lettura, con i riepiloghi di eventi e grafici dei percorsi. Geometria completa del progetto, file, scrittura e sincronizzazione richiedono un contratto partner separato.
Stato del contratto: gli endpoint qui sotto descrivono il comportamento attuale in produzione per i client approvati. Non sono ancora un’API pubblica con versionamento. Non sviluppare contro di essi finché Parkour Design non ha confermato accesso, scope, limiti e contratto di lancio.
URL di base e autenticazione
Usa come URL di base dell’API l’emittente scelto per l’ambiente OAuth:
| Ambiente | URL di base |
|---|---|
| Produzione | https://app.parkour.design |
| Test | https://parkour-test.web.app |
Invia il token di accesso di Parkour Design da un servizio backend:
Authorization: Bearer <access_token>
Accept: application/json
Il token di accesso deve essere valido per l’emittente configurato e l’audience parkour-api, avere token_use uguale a access_token e, attualmente, contenere openid.
L’API attualmente non consente l’accesso da browser di altra origine. Non esporre token di accesso o refresh token al JavaScript del frontend.
Elenco degli eventi
GET /api/events
Esempio di richiesta:
curl "${ISSUER}/api/events" \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--header "Accept: application/json"
Esempio di risposta:
{
"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
}
]
}
Tipo di risposta attuale:
type EventSummary = {
id: string;
name: string;
startDate: string | null;
endDate: string | null;
updatedAt: string | null;
designCount: number;
};
type EventsResponse = {
items: EventSummary[];
};
Gli eventi vengono ricavati dai progetti non eliminati dell’utente autenticato. I progetti senza identificatore di evento vengono omessi.
Tratta id come opaco. Copialo invariato nella richiesta dei riepiloghi dei progetti. Non trarre conclusioni dal suo formato e non generarlo nel sistema del partner.
Elenco dei riepiloghi dei progetti di un evento
GET /api/events/{eventId}/designs
Esempio di richiesta:
curl "${ISSUER}/api/events/${EVENT_ID}/designs" \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--header "Accept: application/json"
Esempio di risposta:
{
"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"
}
]
}
Tipo di risposta attuale:
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[];
};
Le date sono stringhe ISO 8601 in UTC, quando presenti. I client devono gestire null per le date facoltative e per localId.
Proprietà e visibilità
Il sub del bearer token identifica il proprietario della risorsa in Parkour Design. Le risposte contengono solo i progetti non eliminati di proprietà di quell’utente.
Il servizio attuale non fornisce:
- accesso per intere organizzazioni o team;
- accesso ai progetti condivisi o pubblici di un altro utente;
- filtraggio delle risorse specifico per client;
- progetti eliminati;
- dati di abbonamento, profilo o pagamento.
Un evento inesistente e un evento di proprietà di un altro utente restituiscono entrambi 404. Non usare la risposta per dedurre se esiste una risorsa di un altro utente.
Limiti attuali e ordinamento
Gli endpoint attuali non accettano parametri di filtro, ordinamento, paginazione, cursori o sincronizzazione incrementale.
/api/eventsrestituisce l’elenco ricavato degli eventi in una sola risposta./api/events/{eventId}/designsrestituisce al massimo 500 riepiloghi.- La risposta attualmente non indica se l’elenco è stato troncato e non fornisce un cursore di continuazione.
- L’ordinamento è il comportamento dell’implementazione attuale e non ancora una garanzia con versionamento.
Prima di approvare un’integrazione per la produzione, Parkour Design e il partner devono confermare che il volume di dati previsto rientri nei limiti. Un partner che ha bisogno di paginazione completa o aggiornamenti incrementali non deve compensare con scraping o indovinando gli identificatori; serve un contratto rivisto.
Risposte di errore
Gli errori usano un corpo JSON compatto:
{"error": "not_found"}
| Stato | Errore | Significato |
|---|---|---|
401 | invalid_token | Bearer token mancante, malformato, scaduto, non valido o con ambito attualmente insufficiente |
404 | not_found | Percorso non valido o evento non accessibile per l’utente |
405 | method_not_allowed | Metodo diverso da GET |
Gli errori imprevisti del servizio non hanno ancora uno schema di errore separato con versionamento. I client devono considerare ripetibili le altre risposte 5xx solo per le operazioni GET idempotenti, con un backoff esponenziale limitato e jitter.
Dati non esposti dall’API
Il riepilogo di un progetto non è un grafico del percorso completo. L’attuale API delle risorse non espone:
- geometria del percorso o tracciato;
- ostacoli, gruppi, disposizione del campo o oggetti di disegno;
- PDF generati, anteprime, immagini o URL di download;
- operazioni di creazione, aggiornamento, eliminazione o caricamento;
- ricerca di un singolo progetto tramite il suo ID;
- webhook o un flusso delle modifiche;
- token di accesso, sessioni, categorie, attività o destinazioni salvate di Eqify.
Non presentare una risposta con i riepiloghi come un grafico del percorso da stampare o modificare.