| Sommaire |
|---|
...
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é.
...
| Info |
|---|
| Le paramètre pegase.accesstoken.duration (application.properties) permet d'indiquer la durée (en heure) de conservation du token. |
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.
...
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 :
| Bloc de code |
|---|
# Se rendre dans le répertoire d'installation cd E:/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 5.4.0 openapi-generator-cli version-manager set 5.4.0 # Aide sur la config npx @openapitools/openapi-generator-cli config-help -g jav |
Génération du client java
Exemple pour générer les classes de clients java des principales API :
...
| Bloc de code | ||||
|---|---|---|---|---|
| ||||
# INS GESTION YAML npx @openapitools/openapi-generator-cli generate -i ins-gestion-api-v5-16.0.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 # CHC YAML npx @openapitools/openapi-generator-cli generate -i chc-application-api-v5-2.4.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-16.0.0.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 # COC GESTION YAML npx @openapitools/openapi-generator-cli generate -i coc-publication-api-v1-1.1.0.yml -g java -o C:/tmp/openapi-generator/ -p apiPackage=fr.univlorraine.pegase.api.coc -p modelPackage=fr.univlorraine.pegase.model.coc -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
| URL | 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/cursus/{codeStructure}/apprenants/{codeApprenant}/periodes/{codePeriode} | CHC | lireArbreCursusDesInscriptions | 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".
...
- 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
| Bloc de code |
|---|
POST https://authn-app.[univ].pc-scol.fr/cas/v1/tickets?username=[username]&password=[password] |
...
- pegase.accesstoken.url
- pegase.accesstoken.username
- pegase.accesstoken.password
Appel de l'API
| Bloc de code |
|---|
GET https://ins.[univ].pc-scol.fr/api/v5/ins/gestion/inscription/[codeEtablissement]/[codeApprenant]/ |
...