API

Description de l'API REST d'accès aux ressources de l'application.

Toutes les urls nécessitent d'être un utilisateur authentifié dans l'application. Les réponses sont généralement de la forme :
Réponse
data Données correspondants à la ressource demandées
message Message renseignant l'action effectué ou l'erreur rencontrée
success "true" si la requête s'est bien passée, "false" en cas de problème

C'est pourquoi dans la suite, les parties "Réponse" décriront seulement la partie "data".

L'accès à toutes les ressources REST nécessite l'authentification de l'utilisateur dans l'application Esup-Geisha. Par conséquent, les ressources sont par défaut accessible à tous les utilisateurs, i.e. tous les utilisateurs authentifiés et donc pas l'utilisateur anonyme.

Pour chaque ressource, nous indiquons les droits en lecture [r] et en écriture [w]

Ressources générales

/session [r]
  • GET : récupération des données de session, stockées dans Geisha.session. Exception au format data-message-success.
    Réponse
    user utilisateur authentifié
    admin "true" si l'utilisateur est un administrateur, "false" sinon
    displayName nom à afficher de l'utilisateur récupéré dans l'annuaire LDAP
    geishaId numéro HARPEGE de l'utilisateur (0 si inexistant)
    id identifiant LDAP de l'utilisateur
    mail adresse mail de l'utilisateur
    individu individu GEISHA correspondant au geishaId de l'utilisateur ou sélectionné par l'administrateur.
    id numéro HARPEGE de l'individu
    civilité civilité de l'individu
    nom nom de l'individu
    prenom prénom de l'individu
    annees liste des libellés des années universitaires
/individus [r]
  • GET : recherche d'individus.
    Paramètre
    q chaîne de caractères à rechercher dans les noms et prénoms des individus GEISHA
    Réponse
    data tableau d'individus correspondants à la recherche
/users [r]
  • GET : recherche d'utilisateurs.
    Paramètre
    q chaîne de caractères à rechercher dans l'annuaire LDAP
    Réponse
    data tableau d'utilisateurs correspondants à la recherche
/admins [rw]
  • GET : récupération de la liste des administrateurs (type user),
  • POST : ajout d'un administrateur à partir de son identifiant passé dans le paramètre "id".
    Paramètre
    id identifiant du nouvel administrateur
    Réponse
    data le nouvel administrateur (cf. user)
  • Les méthodes DELETE et PUT ne sont pas autorisées.
  • La ressource est accessible uniquement aux administrateurs.
/admins/{id} [rw]
  • GET : récupération de l'administrateur d'identifiant {id},
  • DELETE : suppression de l'administrateur d'identifiant {id}.
  • Les méthodes POST et PUT ne sont pas autorisées.
  • La ressource est accessible uniquement aux administrateurs.

Ressources liées aux services annuels.

/san [r]
  • GET : liste des services annuels pour un individu et une année donnée. Un élément "compteur" est ajouté en plus de la partie "data".
    Paramètres
    uid identifiant de l'individu1
    annee libelle de l'année universitaire2
    Réponse
    compteurs les compteurs globaux
    serviceAssure service assuré
    serviceCompta service comptabilisé
    serviceStatut service statutaire
    serviceDu service du
    hcNonPayables heures complémentaires non payables
    hcPayables heures complémentaires payables
    limite limite d'heures complémentaires
    data la liste des services annuels correspondants
    annee libellé de l'année universitaire
    compteurs compteurs particulier pour ce service annuel
    individu individu effectuant le service
    structure structure d'affectation ou de recrutement pour le service (id, lc, ll = identifiant, libellé court, libellé long)
    structureFormation structure possédant les formations
    typeIntervenant type d'intervenant ('P' pour un permanent, 'E' pour un intervenant extérieur)
/san/{id} [rw]
  • L'identifiant id doit correspondre au code d'une structure pour laquelle l'individu possède un SAN pour l'année indiquée.
  • GET : le service annuel dont la structure à l'identifiant {id}.
    Paramètres
    uid identifiant de l'individu1
    annee libelle de l'année universitaire2
    Réponse
    data le service annuel correspondant
  • PUT : rechargement d'un service annuel (utilisé après modification d'un destinataire ou d'une ligne service pour recharger les compteurs).
    Paramètres
    uid identifiant de l'individu1
    annee libelle de l'année universitaire2
    Réponse
    compteurs les compteurs globaux
    data le service annuel correspondant
  • Les méthodes POST et DELETE ne sont pas autorisées.
/destinataires [rw]
  • L'ajout d'un destinataire n'est autorisé que si l'année universitaire correspond à l'année courante (TODO : à revoir lorsqu'on aura les périodes de saisie).
  • GET : liste des destinataires services d'un SAN.
    Paramètres
    uid identifiant de l'individu1
    annee libelle de l'année universitaire2
    structure identifiant de la structure d'affectation ou de recrutement pour le SAN
    Réponse
    data liste de destinataires services du SAN
    discipline la discipline : id, libelle
    elp unité d'enseignement : id, lc, ll
    enseignement entrée libre pour le code étape
    id identifiant du destinataire
    regime régime d'inscription : id, libelle
    structure structure destinataire des services
    vdi version de diplôme : code, version, libelle
    vet version d'étape : code, version, lc, ll, structure (dispensant cette version d'étape), uesOwner ("true" si elle possède des UEs, "false" sinon)
    volume volume équivalent TD des services
    fin date de fin de validité si le destinataire a été annulé
  • POST : ajout d'un nouveau destinataire.
    Paramètres
    uid identifiant de l'individu1
    annee libelle de l'année universitaire2
    structure identifiant de la structure d'affectation ou de recrutement pour le SAN
    data le nouveau destinataire encodé en JSON
    Réponse
    data le nouveau destinataire
  • Les méthodes PUT et DELETE ne sont pas autorisées.
/destinataires/{id} [rw]
  • id doit être l'identifiant d'un destinataire service. L'individu associé à ce destinataire doit correspondre à l'utilisateur authentifié ou celui-ci doit être administrateur.
  • La modification ou suppression du destinataire n'est autorisée que si l'année universitaire associée correspond à l'année courante (TODO : à revoir lorsqu'on aura les périodes de saisie).
  • GET : le destinataire d'identifiant {id}.
  • DELETE : suppression du destinataire.
  • PUT : modification du destinataire
    Paramètres
    data le destinataire modifié encodé en JSON
    Réponse
    data le destinataire modifié
  • La méthode POST n'est pas autorisée.
/lignes [rw]
  • Le paramètre destinataire doit être l'identifiant d'un destinataire service. L'individu associé à ce destinataire doit correspondre à l'utilisateur authentifié ou celui-ci doit être administrateur.
  • L'ajout d'une ligne n'est autorisé que si l'année universitaire associée au destinataire correspond à l'année courante (TODO : à revoir lorsqu'on aura les périodes de saisie).
  • GET : liste des lignes services d'un destinataire.
    Paramètres
    destinataire identifiant du destinataire3
    Réponse
    data liste des lignes services du destinataire
    id identifiant de la ligne service
    typeIntervention type d'intervention : id, libelle, coeff (coefficient équivalent TD)
    motifNonPaiement motif de non paiement (si besoin)
    periode type de période : id, libelle
    etat état de la ligne service : id, libelle
    volume volume horaire
    fin date de fin de validité si la ligne a été annulée
  • POST : ajout d'une ligne service.
    Paramètres
    data la nouvelle ligne encodée en JSON
    Réponse
    data la nouvelle ligne service
  • Les méthodes PUT et DELETE ne sont pas autorisées.
/lignes/{id} [rw]
  • id doit être l'identifiant d'une ligne service. L'individu associé à cette ligne doit correspondre à l'utilisateur authentifié ou celui-ci doit être administrateur.
  • La modification ou suppression de la ligne n'est autorisée que si l'année universitaire associée correspond à l'année courante (TODO : à revoir lorsqu'on aura les périodes de saisie).
  • GET : la ligne service d'identifiant {id}.
  • DELETE : suppression de la ligne service.
  • PUT : modification de la ligne service
    Paramètres
    data la ligne modifiée encodée en JSON
    Réponse
    data la ligne modifiée
  • La méthode POST n'est pas autorisée.
/structures [r]
  • Si le paramètre node vaut "root", les paramètres uid, annee et structure doivent identifier un SAN l'utilisateur. Les structures renvoyées dépendent du type d'intervenant :
    • pour un intervenant extérieur, la structure de recrutement et la composante correspondante (le cas échéant),
    • pour un permanent, la structure d'affectation, la composante correspondante (le cas échéant), l'établissement et la structure racine (Autres).
  • Sinon, la paramètre node doit être un code structure valide. Les structures filles sont alors renvoyées.
  • GET : noeud(s) de l'arbre des structures.
    Paramètres
    uid identifiant de l'invidu.
    annee libellé de l'année universitaire
    structure identifiant de la structure correspondant au SAN sélectionné
    node identifiant de la structure dont on veut les structures filles ("root" = structure racine)
    Réponse
    data liste des noeuds enfants dans l'arbre des structures
    id identifiant du noeud
    lc libellé court
    ll libellé long
    text texte du noeud
    qtip texte de l'infobulle
    leaf "true" si le noeud est une feuille de l'arbre, "false" si la structure correspondante possède des structures filles
    data la structure associée au noeud
/ues [r]
  • Si le paramètre type vaut 'structure', le paramètre node doit être un code structure valide.
  • Si le paramètre type vaut 'vet', le paramètre node doit être un couple '<code>-<version>' identifiant une VET.
  • Si le paramètre type vaut autre chose, un tableau vide est renvoyé.
  • GET : noeud(s) de l'arbre des formations. Permet de récupérer les VET d'une structure ou les UEs d'une VET.
    Paramètres
    node identifiant du noeud dont on veut les enfants
    type type du noeud : 'structure' (noeud racine), 'vet' ou 'ue'
    Réponse
    data liste des noeuds enfants dans l'arbre des structures
    id identifiant du noeud
    code code de la VET ou identifiant de l'UE
    version version de la VET
    lc libellé court
    ll libellé long
    text texte du noeud
    qtip texte de l'infobulle
    leaf "true" si le noeud est une feuille de l'arbre, "false" si la structure correspondante possède des structures filles
    type type du noeud
    data VET ou UE associée au noeud

Ressources liées aux données statiques.

/disciplines [r]
  • GET : liste des disciplines.
/regimes [r]
  • GET : liste des régimes d'inscription.
/periodes [r]
  • GET : liste des types de période possibles pour les lignes services d'un destinataire. En fait, les périodes sont définies pour une structure, une année universitaire et un type d'intervenant donnés.
    Paramètres
    destinataire l'identifiant du destinataire service
    Réponse
    data la liste des types de période acceptés pour les lignes services du destinataire
/interventions [r]
  • GET : liste des types d'intervention.
/motifs [r]
  • GET : liste des motifs de non paiement.

Ressources liées aux demandes de dépassement.

/depassements [rw]
  • GET : liste des demandes de dépassement d'un individu,
    Paramètres
    uid identifiant de l'individu
    Réponse
    data la liste des demandes de dépassement de l'individu
    id identifiant de la demande
    individu individu effectuant la demande
    annee année universitaire ciblée
    limiteDem limite demandée
    texteDem motivation de la demande
    dateDem date de la demande
    avis liste des avis des directeurs de composante : dirCmp, type (type d'avis), texte, date
    limiteDec limite décidée
    texteDec motivation de la décision
    dateDec date de la décision
    compteurs compteurs globaux
  • POST : ajout d'une nouvelle demande
    Paramètres
    uid identifiant de l'individu
    data nouvelle demande encodée en JSON, avec uniquement la motivation et la limite demandée
    Réponse
    data la nouvelle demande complète
  • Les méthodes PUT et DELETE ne sont pas autorisée.
/depassements/{id}
  • id doit être l'identifiant d'une demande de dépassement. L'individu associé à cette demande doit correspondre à l'utilisateur authentifié ou celui-ci doit être administrateur.
  • La suppression d'une demande n'est possible que pour une demande en cours.
  • La modification d'une demande n'est pas possible. Il faut supprimer la demande en cours (le cas échéant) et faire une nouvelle demande.
  • GET : la demande d'identifiant {id}.
  • DELETE : suppression de la demande.
  • Les méthodes POST et PUT ne sont pas autorisée.

Ressources liées à la validation.

/validation/{valideur}/etats [r]
  • valideur doit correspondre au numéro HARPEGE de l'utilisateur ou celui-ci doit être administrateur.
  • GET : listes de états à valider pour l'individu identifié par {valideur}. A chaque instant, un valideur ne peut valider un état que pour une phase (ou couple phase principale - phase destinataire). L'identifiant de l'état identifie donc également le triplet état - phase principale - phase destinataire pour le valideur.
    Réponse
    etat état à valider
    id identifiant de l'état
    individu individu effectuant les services à valider
    annee année universitaire correspondant aux services
    periode période des services à valider
    phase numéro de la phase actuelle de validation de l'état
    phaseDst numéro de la phase destinataire actuelle de validation de l'état
    typeEtat type d'état ([R]écapitulatif, [L]iquidatif)
    typeIntervenant type d'intervenant ([P]ermanent, intervenant [E]xtérieur)
    wfCmp élément du workflow de la structure principale
    structure structure correspondant au workflow
    typeEtat type d'état correspondant au workflow
    ordre numéro d'ordre de la phase dans le workflow
    phase phase de validation : code, libelle
    wfCmpDst élément du workflow de la structure destinataire (idem wfCmp, absent si la phase principale n'est pas 'STR_DST')
/validation/{valideur}/etats/{etat} [rw]
  • Le paramètre etat doit identifier un état à valider pour lequel le valideur a des validations en attente.
  • GET : l'état à valider d'identifiant {etat}
  • DELETE : validation de l'état (car suppression de la liste des états à valider)
    Réponse
    data le nombre de lignes services validées
  • Les méthodes POST et PUT ne sont pas autorisées.
/validation/{valideur}/destinataires [rw]
  • Le paramètre etat doit identifier un état à valider pour lequel le valideur a des validations en attente.
  • L'ajout d'un destinataire service est soumis à vérification des droits de validation en fonction de la structure et de la phase de validation.
  • GET : listes des destinataires de lignes services à valider par le valideur pour l'état passé en paramètre
    Paramètre
    etat identifiant de l'état à valider
    Réponse
    data liste des destinataires de lignes services à valider par le valideur pour l'état
    id identifiant du destinataire
    structure structure destinataire des services
    vdi version de diplôme : code, version, libelle
    vet version d'étape : code, version, lc, ll, structure (dispensant cette version d'étape), uesOwner ("true" si elle possède des UEs, "false" sinon)
    elp unité d'enseignement : id, lc, ll
    enseignement entrée libre pour le code étape
    discipline la discipline : id, libelle
    regime régime d'inscription : id, libelle
    volume volume équivalent TD des services
    fin date de fin de validité si le destinataire a été annulé
    validations nombre de lignes à valider pour ce destinataire
  • POST : ajout d'un nouveau destinataire pour l'état.
    Paramètres
    etat identifiant de l'état à valider
    data le nouveau destinataire encodé en JSON
    Réponse
    data le nouveau destinataire
  • Les méthodes PUT et DELETE ne sont pas autorisée.
/validation/{valideur}/destinataires/{id} [rw]
  • Le paramètre id doit être un identifiant valide de destinataire service.
  • L'accès à la ressource est soumis à vérification des droits de validation en fonction de la structure et de la phase de validation.
  • GET : le destinataire d'identifiant {id} et son nombre de lignes à valider.
  • DELETE : suppression du destinataire.
  • PUT : modification du destinataire
    Paramètres
    data le destinataire modifié encodé en JSON
    Réponse
    data le destinataire modifié
  • La méthode POST n'est pas autorisée.
/validation/{valideur}/lignes [rw]
  • Le paramètre destinataire doit être l'identifiant d'un destinataire service.
  • L'ajout d'une ligne est soumis à vérification des droits de validation sur ce destinataire en fonction de la structure et de la phase de validation.
  • GET : liste des lignes services, d'un destinataire, à valider pour le valideur.
    Paramètres
    destinataire identifiant du destinataire3
    Réponse
    data liste des lignes services, du destinataire, à valider pour le valideur
    id identifiant de la ligne service
    typeIntervention type d'intervention : id, libelle, coeff (coefficient équivalent TD)
    motifNonPaiement motif de non paiement (si besoin)
    periode type de période : id, libelle
    etat état de la ligne service : id, libelle
    volume volume horaire
    fin date de fin de validité si la ligne a été annulée
    validation code d'état de validation : 'A' pour en attente, 'V' pour valider
  • POST : ajout d'une ligne service.
    Paramètres
    data la nouvelle ligne encodée en JSON
    Réponse
    data la nouvelle ligne service
  • Les méthodes PUT et DELETE ne sont pas autorisées.
/validation/{valideur}/lignes/{id} [rw]
  • id doit être l'identifiant d'une ligne service. A cette ligne doit correspondre une ligne de validation pour le valideur.
  • GET : la ligne service d'identifiant {id}.
  • DELETE : suppression de la ligne service.
  • PUT : modification de la ligne service
    Paramètres
    data la ligne modifiée encodée en JSON
    Réponse
    data la ligne modifiée
  • La méthode POST n'est pas autorisée.
/validation/{valideur}/structures [r]
  • Le paramètre etat doit identifier un état à valider pour lequel le valideur a des validations en attente.
  • Si le paramètre node vaut "root", les structures renvoyées dépendent de la phase de validation :
    • pour la phase STR_DST, la structure du workflow destinataire,
    • pour la phase RES_FOR, la structure du workflow principal,
    • pour les autres phases, on reprend la règle de la ressource correspondante dans la partie saisie du service.
  • Sinon, la paramètre node doit être un code structure valide. Les structures filles sont alors renvoyées.
  • GET : noeud(s) de l'arbre des structures.
    Paramètres
    etat identifiant de l'état à valider
    node identifiant de la structure dont on veut les structures filles ("root" = structure racine)
    Réponse
    data liste des noeuds enfants dans l'arbre des structures
    id identifiant du noeud
    lc libellé court
    ll libellé long
    text texte du noeud
    qtip texte de l'infobulle
    leaf "true" si le noeud est une feuille de l'arbre, "false" si la structure correspondante possède des structures filles
    data la structure associée au noeud
/validation/{valideur}/ues [r]
  • Le paramètre etat doit identifier un état à valider pour lequel le valideur a des validations en attente.
  • Si le paramètre type vaut 'structure', le paramètre node doit être un code structure valide correspondant à un choix possible pour le valideur en fonction de la phase.
  • Si le paramètre type vaut 'vet', le paramètre node doit être un couple '<code>-<version>' identifiant une VET et la structure associée doit également correspondre à un choix possible pour le valideur en fonction de la phase.
  • Si le paramètre type vaut autre chose, un tableau vide est renvoyé.
  • GET : noeud(s) de l'arbre des formations. Permet de récupérer les VET d'une structure ou les UEs d'une VET.
    Paramètres
    node identifiant du noeud dont on veut les enfants
    type type du noeud : 'structure' (noeud racine), 'vet' ou 'ue'
    Réponse
    data liste des noeuds enfants dans l'arbre des structures
    id identifiant du noeud
    code code de la VET ou identifiant de l'UE
    version version de la VET
    lc libellé court
    ll libellé long
    text texte du noeud
    qtip texte de l'infobulle
    leaf "true" si le noeud est une feuille de l'arbre, "false" si la structure correspondante possède des structures filles
    type type du noeud
    data VET ou UE associée au noeud

1 L'identifiant doit correspondre au numéro HARPEGE de l'utilisateur, sauf s'il est administrateur. Si l'identifiant est absent, on prend le numéro HARPEGE de l'utilisateur.

2 Si le libellé de l'année universitaire est absent, on prend l'année courante.

3 L'individu lié au destinataire service doit correspondre au numéro HARPEGE de l'utilisateur, sauf s'il est administrateur.