API-referentie¶
Let op: de complete API-referentie wordt onderhouden in het Engels. Voor de actuele endpoint-specificatie, request-/response-schema's en code-voorbeelden, raadpleeg de Engelse API-referentie.
Inleiding¶
IntroVox biedt een REST-API voor:
- De stappen van een tour ophalen (gefilterd op taal + groepen): de welkomsttour, of met
?tour=<id>een tour voor een app of pagina - Tour-start-/voltooiings-/skip-events vastleggen: voor de welkomsttour als telemetrie, voor een tour voor een app per gebruiker (
tour_<id>_seen,_completed,_skipped) - Tours beheren (admin): lijst, aanmaken, wijzigen, aan/uit, verwijderen, opnieuw tonen, statistieken per tour, een hele tour exporteren en importeren
- Bijhouden hoe ver gebruikers in een tour komen (
tour_<id>_reached), alleen bij een run die vanzelf startte - Admin-CRUD op stappen, talen en globale instellingen, per tour
- De per-gebruiker-voorkeuren
wizard_disabled(welkomsttour klaar) entours_disabled(Start tours by themselves uit) beheren, en de tours voor apps die een gebruiker kan krijgen opvragen - Afbeeldingen, video's en ondertitels in stappen uploaden en tonen
- Een optionele abonnementssleutel valideren (beperkt niets)
Authenticatie¶
Endpoints vereisen een actieve Nextcloud-sessie of een app-wachtwoord; geen enkele route is zonder inloggen bereikbaar. Admin-endpoints checken aanvullend IGroupManager::isAdmin().
Alle endpoints vereisen een geldig CSRF-token, ook GET-verzoeken, op twee na. GET /media/{file}, omdat een <img> of <video> geen token kan meesturen: die route leest alleen, vraagt een ingelogde gebruiker met strict cookies, en geeft op alles wat hij weigert dezelfde 404. GET /tour/{id}, een deellink uit een mail, die ook geen token kan meesturen: die vraagt een ingelogde gebruiker, verandert niets en stuurt alleen door naar de pagina van de tour. Gebruik in de frontend @nextcloud/axios, dat het token automatisch meestuurt. tests-js/controller-security.test.js laat de build falen als een route #[PublicPage] krijgt, als een andere route dan die twee #[NoCSRFRequired] krijgt, of als de frontend de API met fetch() aanroept.
Alles wat geweigerd wordt bij de stappen of events van een tour voor een app (onbekende tour, tour uit, gebruiker niet in de groepen of zonder toegang tot de app) krijgt dezelfde 404 { "success": false }, zodat het antwoord niets verraadt over welke tours er zijn. POST /api/tours/{id}/event heeft een limiet van 30 verzoeken per uur per gebruiker, POST /api/tours/{id}/reached (ook voor de welkomsttour) 300.
Endpoint-categorieën¶
| Categorie | Doel |
|---|---|
| Stappen | GET /api/steps (gefilterd; ?tour=<id> voor een tour voor een app), GET /admin/steps (admin) |
| Tracking | /api/wizard/start, /complete, /skip voor de welkomsttour; POST /api/tours/{id}/event (start, complete, skip) voor een tour voor een app; POST /api/tours/{id}/reached (verste stap) voor elke tour |
| Checklist | POST /api/checklist/{id}: een eigen taak van de checklist op het Dashboard is vanuit de lijst geopend (de pagina draagt ?introvox-check=<id>) |
| Deellink | GET /tour/{id} (wat Copy link geeft): eerst inloggen als dat nodig is, dan door naar de pagina van de tour met ?introvox-tour=<id>, dat die tour daar start, als een start met de hand; alleen voor wie de tour mag krijgen |
| Tours (admin) | GET/POST /admin/tours, PUT/DELETE /admin/tours/{id}, POST /admin/tours/{id}/reshow, GET /admin/tours/{id}/statistics, GET /admin/tours/{id}/export (.zip), POST /admin/tours/import, GET /admin/apps |
| Assistant (admin) | GET /admin/assistant (is er een provider), POST /admin/assistant/translate (tour, from, to), POST /admin/assistant/draft (tour, description, lang), GET /admin/assistant/tasks/{id} (running, done met stappen, of failed met een reden) |
| Admin-stap-CRUD | saveSteps, resetToDefault, importSteps, exportSteps — elk met een parameter tour (standaard welcome) |
| Admin-instellingen | saveSettings (enabled = Tours for everyone, userMenu, checklist; alleen wat meekomt verandert; de welkomsttour opnieuw tonen gaat via POST /admin/tours/welcome/reshow), toggleTelemetry, sendTelemetryNow, markTelemetryAsked, markIntroDone |
| Talen | getAvailableLanguagesWithMetadata (alle talen van Nextcloud), listOverrides (per tour) |
| Media | POST /admin/media, POST /admin/media/from-files, GET /media/{file} |
| Persoonlijk | GET/POST /personal/settings (wizardDisabled, toursDisabled, lijst met tours); GET geeft ook toursEnabled (Tours for everyone). <introvox-tour-list> in andere apps leest hetzelfde antwoord |
| Licentie | Een optionele abonnementssleutel valideren en het gebruik rapporteren; niets in IntroVox wordt erdoor beperkt, en de beheerpagina roept deze routes niet aan |
Voor de complete referentie¶
Zie api-reference.md voor:
- Volledige request-/response-schema's per endpoint, ook het tour-object
- HTTP-statuscodes en error-formaat
- Het stap-object
- Filtering-implementatie-details
Zie ook¶
- Backend-architectuur — controllers en services
- Frontend-architectuur — Vue-client
- Architectuur-overzicht — systeem-design