Architecture
MDW est autorisé à interroger les APIs Pégase en s'identifiant à l'aide d'un token (JWT). Ce dernier est obtenu en s'authentifiant (username + passwordd) auprès du serveur OAuth dédié.
Ce token a une durée de vie limitée. MDW garde donc ce token en mémoire et vérifie régulièrement sa validité afin de le renouveller si nécessaire.
Génération des classes clientes
MDW embarque directement dans son code les classes java clientes utilisées pour interroger les APIs. Il n'y a pas de dépendance vers une librairie externe.
Pour générer ces classes java, OpenAPI Generator est utilisé depuis la v1.
Dans un soucis de transparence et afin de permettre de rejouer cette procédure (normalement pas nécessaire), voici, ci-dessous, la démarche utilisée lors du développement.
Installation d'OpenAPI Generator
Télécharger la version zip de node (https://nodejs.org/en/download/) et dézipper puis :
# Se rendre dans le répertoire d'installation cd C:/node-v14.16.0-win-x64 # Installer openapi-generator-cli npm install @openapitools/openapi-generator-cli npm install @openapitools/openapi-generator-cli -g # Forcer l'utilisation de la version 4.3.1 openapi-generator-cli version-manager set 4.3.1 # Aide sur la config npx @openapitools/openapi-generator-cli config-help -g java
Génération du client java
Exemple pour générer les classes de clients java des principales API :
Copier les YML dans C:\tmp\YML et lancer depuis le répertoire où se trouve le YAML une génération java :
# INS GESTION YAML npx @openapitools/openapi-generator-cli generate -i ins-gestion-api-v5-2.2.0.yaml -g java -o C:/tmp/openapi-generator/ -p apiPackage=fr.univlorraine.pegase.api.insgestion -p modelPackage=fr.univlorraine.pegase.model.insgestion -p dateLibrary=java8-localdatetime # CURSUS YAML npx @openapitools/openapi-generator-cli generate -i chc-application-api-v5-1.0.0.yml -g java -o C:/tmp/openapi-generator/ -p apiPackage=fr.univlorraine.pegase.api.chc -p modelPackage=fr.univlorraine.pegase.model.chc -p dateLibrary=java8-localdatetime --skip-validate-spec # PAI YAML npx @openapitools/openapi-generator-cli generate -i pai-api-v1-2.1.2.yaml -g java -o C:/tmp/openapi-generator/ -p apiPackage=fr.univlorraine.pegase.api.pai -p modelPackage=fr.univlorraine.pegase.model.pai -p dateLibrary=java8-localdatetime --skip-validate-spec
Récupérer le code généré dans le projet
Pour chaque API, récupérer les classes des répertoires :
/ src/main/java/fr/univlorraine/pegase/api/{NOM_API}
/src/main/java/fr/univlorraine/pegase/model/{NOM_API}
Implémentation
Pour des exemples d'appels aux APIs effectués grâce aux classes générées ci-dessus, voir le code source du PegaseService sur github : https://github.com/EsupPortail/esup-mdw-pegase/blob/master/src/main/java/fr/univlorraine/mondossierweb/service/PegaseService.java
APIs utilisées
API | Module | Méthode | Utilisation |
---|---|---|---|
url_authn-app/cas/v1/tickets/ | serveur OAuth | Récupération du Jeton JWT pour authentification des API | |
url_ins/api/v5/ins/gestion/inscription/${etab}/${codeApprenant} | INS | lireInscriptions | Récupération du dossier de l'apprenant et de ses inscriptions |
url_ins/api/v5/ins/gestion/inscriptions/${etab}/${codeApprenant}/${codeVoeu}/certificat-de-scolarite | INS | imprimerCertificatDeScolarite | Récupération du certificat de scolarité |
url_ins/api/v5/ins/gestion/inscriptions/${etab}/${codeApprenant}/${codeVoeu}/${codePiece}/contenu | INS | contenuPiece | Récupération de la photo de l'étudiant |
url_chc/api/chc/v5/inscriptions/objets-maquette/${codeApprenant}/${codePeriode}/${etab} | CHC | lireListeInscriptionsObjetsMaquettesPourApprenantDansPeriode | Récupération du cursus |
url_coc/api/coc/publication/v1/etablissements/${etab}/periodes/${codePeriode}/apprenants/${codeApprenant}/chemins/${chemin} | COC | listerCursusPubliableApprenant | Récupération des notes et résultats de l'étudiant |
url_pai/api/v1/pai/attestation-de-paiement/${etab}/${codeApprenant}/${codePeriode} | PAI | imprimerAttestationDePaiement | Récupération de l'attestation de paiement |
Tester une API
Nous allons voir comment tester le bon fonctionnement d'une API en la requêtant "à la main".
Appeler une API s'effectue via une requête HTTP.
Pour être autorisé à appeler l'API d'un module Pégase, il faut préalablement avoir récupéré un token d'authentification.
Par exemple pour tester la méthode lireInscriptions de l'API INS (qui retourne la quasi totalité du dossier), il faut :
- Faire un premier appel (POST) au serveur OAuth pour récupérer le token
- Utiliser ce token pour appeler l'API (GET)
Récupération du token
POST https://authn-app.[univ].pc-scol.fr/cas/v1/tickets?username=[username]&password=[password]
Le username et le password à passer sont ceux permettant d'identifier MDW auprès du serveur OAuth de Pégase.
Ces informations correspondent aux paramètres suivant dans application.properties :
- pegase.accesstoken.url
- pegase.accesstoken.username
- pegase.accesstoken.password
Appel de l'API
GET https://ins.[univ].pc-scol.fr/api/v5/ins/gestion/inscription/[codeEtablissement]/[codeApprenant]/
Ajouter la chaîne "Bearer " (attention à bien ajouter l'espace) au début du token et le passer dans un header nommé "Authorization".
L'url de l'API et le code établissement correspondent aux paramètres suivant dans application.properties :
- pegase.api.ins.url
- pegase.etablissement