Partie 9 — Web Services : l’API externe de Moodle
Public : développeur web (Next.js / React / TypeScript) qui veut faire communiquer Moodle avec l’extérieur — une app Next.js, un SIRH, un portail, un script d’intégration. On a construit dans Moodle (Parties 5–8) ; ici on l’ouvre.
Version de référence : Moodle 5.2 (PHP 8.3+, racine web
public/). Web services REST (JSON), tokens, external functions typées via la classe\core_external\external_api.
Moodle n’est pas headless par défaut, mais il expose une API de web services riche et sécurisée : plusieurs milliers de fonctions externes du core (récupérer des cours, inscrire des utilisateurs, lire des notes…), un système de tokens, et la possibilité d’écrire vos propres fonctions. C’est le pont entre Moodle et votre écosystème JavaScript. Cette partie couvre l’architecture, la sécurité, l’usage des fonctions du core, la création de vos fonctions, et un client Next.js complet.
Sommaire de la partie
Chapitre 1 — Architecture des web services
La vue d’ensemble : qu’est-ce qu’une external function, un external service, un protocole (REST en tête). Le flux complet d’un appel (client → endpoint → validation → capability → exécution → réponse typée). Pourquoi les web services sont le même code que l’interface (les external functions servent aussi le JS interne, ch. 7.3). Activer les web services et le protocole REST. La différence entre l’API utilisateur (un token par utilisateur) et l’API système.
Chapitre 2 — Tokens, authentification et sécurité
Le modèle de sécurité : comment obtenir un token (manuel, service mobile, login/token.php), token par utilisateur vs compte de service, la restriction aux fonctions autorisées d’un service, les capabilities requises (webservice/rest:use + celles de chaque fonction), IP restrictions, expiration, et les pièges de sécurité (un token = une identité, ne jamais l’exposer côté client public). Le processus complet côté admin.
Chapitre 3 — Les fonctions externes du core
Le catalogue : où trouver les fonctions (core_course_*, core_enrol_*, core_user_*, gradereport_*…), lire leur signature (paramètres, retour) dans l’API Documentation intégrée, et les appeler en REST (curl + TypeScript). Exemples concrets : lister les cours, inscrire un utilisateur, lire les notes, récupérer le contenu d’un cours. Les conventions de nommage et le format des réponses.
Chapitre 4 — Créer sa propre fonction externe
Le tutoriel : exposer notre plugin local_todolist (Partie 6) en web service. La classe \core_external\external_api, le triptyque execute_parameters() / execute() / execute_returns(), la déclaration dans db/services.php, la validation typée, les capabilities, external_format_string/external_format_text pour la sortie sûre, tester avec l’API tester intégré, et le versionnage.
Chapitre 5 — Consommer l’API depuis Next.js
Le pont complet vers votre monde : un client TypeScript typé, où stocker le token (côté serveur uniquement — route handlers / server actions), gérer les erreurs Moodle (qui renvoie 200 + payload d’erreur), typer les réponses, patterns (cache, revalidation), et une mini-app Next.js qui lit et écrit dans Moodle. Les pièges (CORS, format des paramètres imbriqués, exceptions déguisées en succès HTTP).
Ce que vous saurez faire à la fin de cette partie
- Expliquer l’architecture des web services et le flux d’un appel de bout en bout.
- Configurer un service, générer un token, et sécuriser l’accès (capabilities, IP, expiration).
- Appeler les fonctions du core en REST depuis curl ou TypeScript.
- Écrire votre propre fonction externe typée et sécurisée, et l’exposer.
- Consommer l’API Moodle depuis Next.js proprement (token côté serveur, typage, gestion d’erreurs).
💡 Pour un dev React : voyez les web services comme le backend API de Moodle que vous consommez comme n’importe quelle API — sauf trois spécificités : (1) l’authentification est par token (pas de cookie/JWT standard) ; (2) le protocole REST de Moodle renvoie souvent HTTP 200 même en cas d’erreur (l’erreur est dans le corps) ; (3) chaque fonction est typée côté serveur (paramètres et retour déclarés), un peu comme un endpoint tRPC. Une external function, c’est un route handler sécurisé et typé — celui-là même que
core/ajaxappelle en interne (ch. 7.3).
⚠️ Piège transverse : un token de web service = une identité et ses permissions. Ne l’exposez jamais dans du code client public (bundle JS, navigateur). Côté Next.js, le token vit uniquement côté serveur (variables d’environnement, route handlers, server actions), jamais dans un composant client. C’est le fil rouge de sécurité de toute la partie (détaillé aux chapitres 2 et 5).
Chapitre suivant : 01 — Architecture des web services