DocScoDocMM/ScoDoc9API.md at b56018283a379eb754b9d008bcafefe9db6210b0

viennet b56018283a Merge branch 'master' of https://scodoc.org/git/leonard.montalbano/DocScoDoc

2022-05-06 17:46:07 +02:00

49 KiB

Raw Blame History

API pour ScoDoc 9

L'API ScoDoc permet à des applications tierces d'interroger ScoDoc. Elle offre un accès aux informations aux formats XML et JSON.

La version ScoDoc 9 a introduit une nouvelle API avec un nouveau mécanisme d'authentification. Les clients de l'ancienne API ScoDoc 7 doivent être adaptés pour fonctionner avec ScoDoc 9.

Cette API est encore incomplète: n'hésitez pas à demander de nouveaux accès en écrivant à la liste de diffusion.

L'API fournit des données JSON, sauf exception (bulletins).

Les objets ScoDoc manipulables sont identifiés par des id.

etudid: étudiant
formation_id: un programme de formation (page "programmes");
ue_id: une UE dans un programme;
matiere_id: une matière dans un programme;
module_id: un module dans un programme;
moduleimpl_id: un module réalisé dans un semestre;
formsemestre_id: un "semestre" de formation.

(pour plus de précisions, voir la doc interne)

L'URL complète est de la forme: https://scodoc.example.com/ScoDoc/api/fonction.

Configuration de ScoDoc pour utiliser l'API

Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats.

En général, il est recommandé de créer un rôle, de lui attribuer les permissions que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle.

En ligne de commande, cela peut se faire comme suit (voir détail des commandes sur le guide de configuration).

# se connecter comme utilisateur scodoc
su - scodoc

# Créer un rôle
flask create-role LecteurAPI
# Lui donner les droits nécessaires: ici APIView
flask edit-role LecteurAPI -a APIView

# Créer un nouvel utilisateur avec ce rôle:
flask user-create lecteur_api LecteurAPI @all

# Ou bien, si on veut utiliser un compte existant:
#   associer notre rôle à un utilisateur
flask user-role lecteur_api -a LecteurAPI


# Au besoin, changer le mot de passe de l'utilisateur
# (on aura besoin de ce mot de passe dans la configuration du client d'API)
flask user-password lecteur_api
...

Fonctions d'API ScoDoc 9 (work in progress)

Basé sur le ticket #149

La documentation ci-dessous concerne la future version de ScoDoc (9.3, avec parties expérimentales progressivement mises en production à partir de 9.2.12).

Accès à l'API REST

Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction

Authentification

Lors de votre authentification (connection avec login et mdp) à Scodoc, il vous sera attribué un jeton (token jwt généré automatiquement) vous permettant d'utiliser l'api suivant les droits correspondant à votre session.

Pour obtenir le jeton, il faut un compte sur ScoDoc (user_nameet password). Les autorisations et rôles sont gérés exactement comme pour l'application.

Exemple avec curl (un outil en ligne de commande présent sur la plupart des systèmes):

curl -u user_name:password --request POST https://SERVEUR/ScoDoc/api/tokens

ou la même chose avec http:

http --auth user_name:password POST https://SERVER/ScoDoc/api/tokens

où SERVEUR est l'adresse (IP ou nom) de votre serveur. La réponse doit ressembler à ceci:

{
  "token": "LuXXxk+i74TXYZZl8MulgbiCGmVHXXX"
}

Vous trouverez dans /opt/scodoc/tests/api/exemple-api-basic.py un exemple complet en python d'interrogation de l'API.

Codes HTTP

Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en fonction du résultat obtenu. L'analyse de ce code vous permet de vous assurer que la requête a été traitée avec succès.

Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succès par nos serveurs.

200 : OK.
400 : Paramètre manquant, ou valeur incorrecte.
401 : Authentification nécessaire. (jeton non précisé ou invalide)
403 : Action non autorisée. (crédits épuisés, URL non autorisée, etc)
404 : Page inaccessible. (URL inconnue / impossible d'accéder à l'adresse)
406 : Le JSON indiqué en données POST n'est pas valide.
408 : Dépassement du temps maximal autorisé pour l’audit.
500 : Erreur inconnue, contactez-nous.
503 : L'API est momentanément indisponible, réessayez dans quelques minutes.

Note sur les identifiants de sessions

Le session_id peut être utilisé pour identifier de façon prévisible et (presque) unique une session dans un établissement, ce qui est utile notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion d'emplois du temps ou de services d'enseignement). Cet identifiant est constitué des informations suivantes:

Département (RT, GEII, INFO...) (= paramètre DeptName, en majuscules)
Nom parcours: BUT, LP, ... (défini au niveau du parcours dans ScoDoc = NAME)
Modalité: FI, FC, FA
"Spécialité": S1 (ou S1D pour les semestres décalés), ou le code_specialite si pas de semestres. Le code spécialité est un champ (libre) nouveau dans la "formation" (programme pédagogique).
- Année: année de début de l'année scolaire correspondante (2014 pour une session appartenant à l'année scolaire 2014-2015, même si elle commence en mars 2015).

Exemple: INFO-DUT-FI-S1-2014 équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI)

Départements

departements

Méthode: GET
Routes: /departements
Exemple d'utilisation: /api/departements
Résultat: Liste des départements.

Exemple de résultat:

[
  {
    "id": 1,
    "acronym": "TAPI",
    "description": null,
    "visible": true,
    "date_creation": "Fri, 15 Apr 2022 12:19:28 GMT"
  },
  {
    "id": 2,
    "acronym": "MMI",
    "description": null,
    "visible": false,
    "date_creation": "Fri, 18 Apr 2022 11:20:8 GMT"
  },
  ...
]

liste_etudiants

Méthode: GET
Paramètres: dept, formsemestre_id
Routes: /departements/<string:dept>/etudiants/list ou /api/departements/<string:dept>/etudiants/list/<int:formsemestre_id>
Exemple d'utilisation: /api/departements/MMI/etudiants/list
Résultat: liste des étudiants d'un département, par défaut, ou d'un semestre si renseigné. (json)

Exemple de résultat:

[
  {
    "civilite": "X",
    "code_ine": null,
    "code_nip": null,
    "date_naissance": null,
    "email": null,
    "emailperso": null,
    "etudid": 18,
    "nom": "MOREL",
    "prenom": "JACQUES"
  },
  {
    "civilite": "X",
    "code_ine": null,
    "code_nip": null,
    "date_naissance": null,
    "email": null,
    "emailperso": null,
    "etudid": 19,
    "nom": "FOURNIER",
    "prenom": "ANNE"
  },
  ...
]

liste_semestres_courant

Méthode: GET
Paramètres: dept
Routes: /departements/<string:dept>/semestres_courants
Exemple d'utilisation: /api/departements/MMI/semestres_courants
Résultat: Liste des semestres actifs d'un département donné. (réponse sous format json)

Exemple de résultat:

[
  {
    "date_fin": "31/08/2022",
    "resp_can_edit": false,
    "dept_id": 1,
    "etat": true,
    "resp_can_change_ens": true,
    "id": 1,
    "modalite": "FI",
    "ens_can_edit_eval": false,
    "formation_id": 1,
    "gestion_compensation": false,
    "elt_sem_apo": null,
    "semestre_id": 1,
    "bul_hide_xml": false,
    "elt_annee_apo": null,
    "titre": "Semestre test",
    "block_moyennes": false,
    "scodoc7_id": null,
    "date_debut": "01/09/2021",
    "gestion_semestrielle": false,
    "bul_bgcolor": "white",
    "formsemestre_id": 1,
    "titre_num": "Semestre test semestre 1",
    "date_debut_iso": "2021-09-01",
    "date_fin_iso": "2022-08-31",
    "responsables": [
      12,
      42
    ],
    "titre_court": "BUT MMI"
  },
  ...
]

Etudiants

etudiants_courant

Méthode: GET
Routes: /etudiants/courant ou /etudiants/courant/long
Exemple d'utilisation: /api/etudiants/courant
Résultat: Retourne la liste des étudiants courant (json).

Exemple de résultat:

[
  {
    "id": 1,
    "nip": 1,
    "nom": "MOREL",
    "prenom": "JACQUES",
    "civilite": "X"
  },
  {
    "id": 2,
    "nip": 2,
    "nom": "GILLES",
    "prenom": "MAXIME",
    "civilite": "X"
  }
]

etudiant

Méthode: GET
Paramètres: etudid, nip, ine
Routes: /etudiant/etudid/<int:etudid> ou /etudiant/nip/<int:nip> ou /etudiant/ine/<int:ine>
Exemple d'utilisation: /api/etudiant/nip/1
Résultat: Retourne les informations de l'étudiant correspondant à l'id passé en paramètres. (json)

Exemple de résultat:

{
  "civilite": "X",
  "code_ine": "1",
  "code_nip": "1",
  "date_naissance": "",
  "email": "SACHA.COSTA@example.com",
  "emailperso": "",
  "etudid": 1,
  "nom": "COSTA",
  "prenom": "SACHA",
  "nomprenom": "Sacha COSTA",
  "lieu_naissance": "",
  "dept_naissance": "",
  "nationalite": "",
  "boursier": "",
  "id": 1,
  "codepostaldomicile": "",
  "paysdomicile": "",
  "telephonemobile": "",
  "typeadresse": "domicile",
  "domicile": "",
  "villedomicile": "",
  "telephone": "",
  "fax": "",
  "description": ""
}

etudiant_formsemestres

Méthode: GET
Paramètres: etudid, nip, ine
Routes: : /etudiant/etudid/<int:etudid>/formsemestres ou /etudiant/nip/<int:nip>/formsemestres ou /etudiant/ine/<int:ine>/formsemestres
Exemple d'utilisation: /etudiant/ine/1/formsemestres
Résultat: Retourne la liste des semestres qu'un étudiant a suivis, triés par ordre chronologique. (json)

Exemple de résultat:

[
  {
    "date_fin": "31/08/2022",
    "resp_can_edit": false,
    "dept_id": 1,
    "etat": true,
    "resp_can_change_ens": true,
    "id": 1,
    "modalite": "FI",
    "ens_can_edit_eval": false,
    "formation_id": 1,
    "gestion_compensation": false,
    "elt_sem_apo": null,
    "semestre_id": 1,
    "bul_hide_xml": false,
    "elt_annee_apo": null,
    "titre": "Semestre test",
    "block_moyennes": false,
    "scodoc7_id": null,
    "date_debut": "01/09/2021",
    "gestion_semestrielle": false,
    "bul_bgcolor": "white",
    "formsemestre_id": 1,
    "titre_num": "Semestre test semestre 1",
    "date_debut_iso": "2021-09-01",
    "date_fin_iso": "2022-08-31",
    "responsables": [
      12,
      42
    ],
    "titre_court": "BUT MMI"
  },
  ...
]

etudiant_bulletin_semestre

Méthode: GET
Paramètres: formsemestre_id, etudid, nip, ine
Routes: /etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin ou /etudiant/nip/<int:nip>/formsemestre/<int:formsemestre_id>/bulletin ou /etudiant/ine/<int:ine>/formsemestre/<int:formsemestre_id>/bulletin
Exemple d'utilisation: /etudiant/nip/1/formsemestre/1/bulletin
Résultat: Retourne le bulletin d'un étudiant en fonction de son id et d'un semestre donné. (json)

Exemple de résultat:

{
  "version": "0",
  "type": "BUT",
  "date": "2022-04-27T07:18:16.450634Z",
  "publie": true,
  "etudiant": {
    "civilite": "X",
    "code_ine": "1",
    "code_nip": "1",
    "date_naissance": "",
    "email": "SACHA.COSTA@example.com",
    "emailperso": "",
    "etudid": 1,
    "nom": "COSTA",
    "prenom": "SACHA",
    "nomprenom": "Sacha COSTA",
    "lieu_naissance": "",
    "dept_naissance": "",
    "nationalite": "",
    "boursier": "",
    "fiche_url": "/ScoDoc/TAPI/Scolarite/ficheEtud?etudid=1",
    "photo_url": "/ScoDoc/TAPI/Scolarite/get_photo_image?etudid=1&size=small",
    "id": 1,
    "codepostaldomicile": "",
    "paysdomicile": "",
    "telephonemobile": "",
    "typeadresse": "domicile",
    "domicile": "",
    "villedomicile": "",
    "telephone": "",
    "fax": "",
    "description": ""
  },
  "formation": {
    "id": 1,
    "acronyme": "BUT R&amp;T",
    "titre_officiel": "Bachelor technologique réseaux et télécommunications",
    "titre": "BUT R&amp;T"
  },
  "formsemestre_id": 1,
  "etat_inscription": "I",
  "options": {
    "show_abs": true,
    "show_abs_modules": false,
    "show_ects": true,
    "show_codemodules": false,
    "show_matieres": false,
    "show_rangs": true,
    "show_ue_rangs": true,
    "show_mod_rangs": true,
    "show_moypromo": false,
    "show_minmax": false,
    "show_minmax_mod": false,
    "show_minmax_eval": false,
    "show_coef": true,
    "show_ue_cap_details": false,
    "show_ue_cap_current": true,
    "show_temporary": true,
    "temporary_txt": "Provisoire",
    "show_uevalid": true,
    "show_date_inscr": true
  },
  "ressources": {
    "R101": {
      "id": 1,
      "titre": "Initiation aux réseaux informatiques",
      "code_apogee": null,
      "url": "/ScoDoc/TAPI/Scolarite/Notes/moduleimpl_status?moduleimpl_id=1",
      "moyenne": {},
      "evaluations": [
        {
          "id": 1,
          "description": "eval1",
          "date": "2022-04-20",
          "heure_debut": "08:00",
          "heure_fin": "09:00",
          "coef": "01.00",
          "poids": {
            "RT1.1": 1
          },
          "note": {
            "value": "12.00",
            "min": "00.00",
            "max": "18.00",
            "moy": "10.88"
          },
          "url": "/ScoDoc/TAPI/Scolarite/Notes/evaluation_listenotes?evaluation_id=1"
        }
      ]
    }
  },
  "saes": {
    "SAE11": {
      "id": 2,
      "titre": "Se sensibiliser à l&apos;hygiène informatique et à la cybersécurité",
      "code_apogee": null,
      "url": "/ScoDoc/TAPI/Scolarite/Notes/moduleimpl_status?moduleimpl_id=2",
      "moyenne": {},
      "evaluations": []
    }
  },
  "ues": {
    "RT1.1": {
      "id": 1,
      "titre": "Administrer les réseaux et l’Internet",
      "numero": 1,
      "type": 0,
      "color": "#B80004",
      "competence": null,
      "moyenne": {
        "value": "08.50",
        "min": "06.00",
        "max": "16.50",
        "moy": "11.31",
        "rang": "12",
        "total": 16
      },
      "bonus": "00.00",
      "malus": "00.00",
      "capitalise": null,
      "ressources": {
        "R101": {
          "id": 1,
          "coef": 12,
          "moyenne": "12.00"
        }
      },
      "saes": {
        "SAE11": {
          "id": 2,
          "coef": 16,
          "moyenne": "~"
        }
      },
      "ECTS": {
        "acquis": 0,
        "total": 12
      }
    },
    "semestre": {
      "etapes": [],
      "date_debut": "2021-09-01",
      "date_fin": "2022-08-31",
      "annee_universitaire": "2021 - 2022",
      "numero": 1,
      "inscription": "",
      "groupes": [],
      "absences": {
        "injustifie": 1,
        "total": 2
      },
      "ECTS": {
        "acquis": 0,
        "total": 30
      },
      "notes": {
        "value": "10.60",
        "min": "02.40",
        "moy": "11.05",
        "max": "17.40"
      },
      "rang": {
        "value": "10",
        "total": 16
      }
    }
  }
}

etudiant_groups
- Méthode: GET
- Paramètres: formsemestre_id, etudid, nip, ine
- Routes: /etudiant/etudid/<int:etudid>/semestre/<int:formsemestre_id>/groups ou /etudiant/nip/<int:nip>/semestre/<int:formsemestre_id>/groups ou /etudiant/ine/<int:ine>/semestre/<int:formsemestre_id>/groups
- Exemple d'utilisation: /etudiant/nip/1/semestre/1/groups
- Résultat: Retourne la liste des groupes auxquels appartient l'étudiant dans le semestre indiqué. (json)
- Exemple de résultat:
```
[
  {
    "partition_id": 1,
    "id": 1,
    "formsemestre_id": 1,
    "partition_name": "TD",
    "numero": 0,
    "bul_show_rank": false,
    "show_in_lists": true,
    "group_id": 1,
    "group_name": "B"
  },
  {
    "partition_id": 2,
    "id": 2,
    "formsemestre_id": 1,
    "partition_name": "TP",
    "numero": 1,
    "bul_show_rank": false,
    "show_in_lists": true,
    "group_id": 2,
    "group_name": "A"
  },
  ...
]
```

Programmes de formations

formations_ids
- Méthode: GET
- Routes: /ScoDoc/api/formations_ids
- Exemple d'utilisation: /ScoDoc/api/formations_ids
- Résultat: Retourne la liste de toutes les id de formations (tous départements)
- Exemple de résultat: [17, 99, 32]

formations_by_id

Méthode: GET
Paramètres: formation_id
Routes: /formations/<int:formation_id>
Exemple d'utilisation: /ScoDoc/api/formations/1
Résultat: Retourne une formation en fonction d'un id donné

Exemple de résultat:

{
  "id": 1,
  "acronyme": "BUT R&amp;T",
  "titre_officiel": "Bachelor technologique réseaux et télécommunications",
  "formation_code": "V1RET",
  "code_specialite": null,
  "dept_id": 1,
  "titre": "BUT R&amp;T",
  "version": 1,
  "type_parcours": 700,
  "referentiel_competence_id": null,
  "formation_id": 1
}

formation_export_by_formation_id

Méthode: GET
Paramètres: formation_id, export_ids (False par défaut. Ajouter /with_ids pour le passer à True)
Routes: /formations/formation_export/<int:formation_id>
Exemple d'utilisation: /ScoDoc/api/formations/formation_export/1
Résultat: Retourne la formation, avec UE, matières, modules

Exemple de résultat:

{
  "id": 1,
  "acronyme": "BUT R&amp;T",
  "titre_officiel": "Bachelor technologique réseaux et télécommunications",
  "formation_code": "V1RET",
  "code_specialite": null,
  "dept_id": 1,
  "titre": "BUT R&amp;T",
  "version": 1,
  "type_parcours": 700,
  "referentiel_competence_id": null,
  "formation_id": 1,
  "ue": [
    {
      "acronyme": "RT1.1",
      "numero": 1,
      "titre": "Administrer les réseaux et l’Internet",
      "type": 0,
      "ue_code": "UCOD11",
      "ects": 12,
      "is_external": false,
      "code_apogee": "",
      "coefficient": 0,
      "semestre_idx": 1,
      "color": "#B80004",
      "reference": 1,
      "matiere": [
        {
          "titre": "Administrer les réseaux et l’Internet",
          "numero": 1,
          "module": [
            {
              "titre": "Initiation aux réseaux informatiques",
              "abbrev": "Init aux réseaux informatiques",
              "code": "R101",
              "heures_cours": 0,
              "heures_td": 0,
              "heures_tp": 0,
              "coefficient": 1,
              "ects": "",
              "semestre_id": 1,
              "numero": 10,
              "code_apogee": "",
              "module_type": 2,
              "coefficients": [
                {
                  "ue_reference": "1",
                  "coef": "12.0"
                },
                {
                  "ue_reference": "2",
                  "coef": "4.0"
                },
                {
                  "ue_reference": "3",
                  "coef": "4.0"
                }
              ]
            },
            {
              "titre": "Se sensibiliser à l&apos;hygiène informatique et à la cybersécurité",
              "abbrev": "Hygiène informatique",
              "code": "SAE11",
              "heures_cours": 0,
              "heures_td": 0,
              "heures_tp": 0,
              "coefficient": 1,
              "ects": "",
              "semestre_id": 1,
              "numero": 10,
              "code_apogee": "",
              "module_type": 3,
              "coefficients": [
                {
                  "ue_reference": "1",
                  "coef": "16.0"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

referentiel_competences
- Méthode: GET
- Paramètres: formation_id
- Routes: /formations/<int:formation_id>/referentiel_competences
- Exemple d'utilisation: api/formations/1/referentiel_competences
- Résultat: Le référentiel de compétences d'une formation donnée (json). (pas toujours présent)
XXX obtenir la liste des référentiels

Semestres de formation

Les sessions de formation (dénommées "semestres" même si elles durent une année ou un mois) sont représentées par les formsemestre.

formsemestre

Méthode: GET
Paramètres: formsemestre_id
Routes: /formsemestre/<int:formsemestre_id>
Exemple d'utilisation: /ScoDoc/api/formsemestre/1
Résultat: Retourne l'information sur le formsemestre correspondant au formsemestre_id

Exemple de résultat:

{
  "date_fin": "31/08/2022",
  "resp_can_edit": false,
  "dept_id": 1,
  "etat": true,
  "resp_can_change_ens": true,
  "id": 1,
  "modalite": "FI",
  "ens_can_edit_eval": false,
  "formation_id": 1,
  "gestion_compensation": false,
  "elt_sem_apo": null,
  "semestre_id": 1,
  "bul_hide_xml": false,
  "elt_annee_apo": null,
  "titre": "Semestre test",
  "block_moyennes": false,
  "scodoc7_id": null,
  "date_debut": "01/09/2021",
  "gestion_semestrielle": false,
  "bul_bgcolor": "white",
  "formsemestre_id": 1,
  "titre_num": "Semestre test semestre 1",
  "date_debut_iso": "2021-09-01",
  "date_fin_iso": "2022-08-31",
  "responsables": [
    12,
    42
  ],
  "titre_court": "BUT MMI"
}

formsemestre_apo

Méthode: GET
Paramètres: etape_apo
Routes: /formsemestre/apo/<string:etape_apo>
Exemple d'utilisation: /ScoDoc/api/formsemestre/1
Résultat: Retourne les informations sur les formsemestres

Exemple de résultat:

[
  {
    "date_fin": "31/08/2022",
    "resp_can_edit": false,
    "dept_id": 1,
    "etat": true,
    "resp_can_change_ens": true,
    "id": 1,
    "modalite": "FI",
    "ens_can_edit_eval": false,
    "formation_id": 1,
    "gestion_compensation": false,
    "elt_sem_apo": null,
    "semestre_id": 1,
    "bul_hide_xml": false,
    "elt_annee_apo": null,
    "titre": "Semestre test",
    "block_moyennes": false,
    "scodoc7_id": null,
    "date_debut": "01/09/2021",
    "gestion_semestrielle": false,
    "bul_bgcolor": "white",
    "formsemestre_id": 1,
    "titre_num": "Semestre test semestre 1",
    "date_debut_iso": "2021-09-01",
    "date_fin_iso": "2022-08-31",
    "responsables": [
      12,
      42
    ],
    "titre_court": "BUT MMI"
  },
  ...
]

bulletins

Méthode: GET
Paramètres: formsemestre_id
Routes: /formsemestre/<int:formsemestre_id>/bulletins
Exemple d'utilisation: /ScoDoc/api/formsemestre/1/bulletins
Résultat: Retourne les bulletins d'un formsemestre donné

Exemple de résultat:

[
  {
    "version": "0",
    "type": "BUT",
    "date": "2022-04-27T07:18:16.450634Z",
    "publie": true,
    "etudiant": {
      "civilite": "X",
      "code_ine": "1",
      "code_nip": "1",
      "date_naissance": "",
      "email": "SACHA.COSTA@example.com",
      "emailperso": "",
      "etudid": 1,
      "nom": "COSTA",
      "prenom": "SACHA",
      "nomprenom": "Sacha COSTA",
      "lieu_naissance": "",
      "dept_naissance": "",
      "nationalite": "",
      "boursier": "",
      "fiche_url": "/ScoDoc/TAPI/Scolarite/ficheEtud?etudid=1",
      "photo_url": "/ScoDoc/TAPI/Scolarite/get_photo_image?etudid=1&size=small",
      "id": 1,
      "codepostaldomicile": "",
      "paysdomicile": "",
      "telephonemobile": "",
      "typeadresse": "domicile",
      "domicile": "",
      "villedomicile": "",
      "telephone": "",
      "fax": "",
      "description": ""
    },
    "formation": {
      "id": 1,
      "acronyme": "BUT R&amp;T",
      "titre_officiel": "Bachelor technologique réseaux et télécommunications",
      "titre": "BUT R&amp;T"
    },
    "formsemestre_id": 1,
    "etat_inscription": "I",
    "options": {
      "show_abs": true,
      "show_abs_modules": false,
      "show_ects": true,
      "show_codemodules": false,
      "show_matieres": false,
      "show_rangs": true,
      "show_ue_rangs": true,
      "show_mod_rangs": true,
      "show_moypromo": false,
      "show_minmax": false,
      "show_minmax_mod": false,
      "show_minmax_eval": false,
      "show_coef": true,
      "show_ue_cap_details": false,
      "show_ue_cap_current": true,
      "show_temporary": true,
      "temporary_txt": "Provisoire",
      "show_uevalid": true,
      "show_date_inscr": true
    },
    "ressources": {
      "R101": {
        "id": 1,
        "titre": "Initiation aux réseaux informatiques",
        "code_apogee": null,
        "url": "/ScoDoc/TAPI/Scolarite/Notes/moduleimpl_status?moduleimpl_id=1",
        "moyenne": {},
        "evaluations": [
          {
            "id": 1,
            "description": "eval1",
            "date": "2022-04-20",
            "heure_debut": "08:00",
            "heure_fin": "09:00",
            "coef": "01.00",
            "poids": {
              "RT1.1": 1
            },
            "note": {
              "value": "12.00",
              "min": "00.00",
              "max": "18.00",
              "moy": "10.88"
            },
            "url": "/ScoDoc/TAPI/Scolarite/Notes/evaluation_listenotes?evaluation_id=1"
          }
        ]
      }
    },
    "saes": {
      "SAE11": {
        "id": 2,
        "titre": "Se sensibiliser à l&apos;hygiène informatique et à la cybersécurité",
        "code_apogee": null,
        "url": "/ScoDoc/TAPI/Scolarite/Notes/moduleimpl_status?moduleimpl_id=2",
        "moyenne": {},
        "evaluations": []
      }
    },
    "ues": {
      "RT1.1": {
        "id": 1,
        "titre": "Administrer les réseaux et l’Internet",
        "numero": 1,
        "type": 0,
        "color": "#B80004",
        "competence": null,
        "moyenne": {
          "value": "08.50",
          "min": "06.00",
          "max": "16.50",
          "moy": "11.31",
          "rang": "12",
          "total": 16
        },
        "bonus": "00.00",
        "malus": "00.00",
        "capitalise": null,
        "ressources": {
          "R101": {
            "id": 1,
            "coef": 12,
            "moyenne": "12.00"
          }
        },
        "saes": {
          "SAE11": {
            "id": 2,
            "coef": 16,
            "moyenne": "~"
          }
        },
        "ECTS": {
          "acquis": 0,
          "total": 12
        }
      },
      "semestre": {
        "etapes": [],
        "date_debut": "2021-09-01",
        "date_fin": "2022-08-31",
        "annee_universitaire": "2021 - 2022",
        "numero": 1,
        "inscription": "",
        "groupes": [],
        "absences": {
          "injustifie": 1,
          "total": 2
        },
        "ECTS": {
          "acquis": 0,
          "total": 30
        },
        "notes": {
          "value": "10.60",
          "min": "02.40",
          "moy": "11.05",
          "max": "17.40"
        },
        "rang": {
          "value": "10",
          "total": 16
        }
      }
    }
  }
]

jury
- Méthode: GET
- Paramètres: formsemestre_id
- Routes: /formsemestre/<int:formsemestre_id>/jury
- Exemple d'utilisation: /ScoDoc/api/formsemestre/1/jury
- Résultat: Retourne le récapitulatif des décisions jury
- Exemple de résultat:
```
XXX A COMPLETER
```

programme

Méthode: GET
Paramètres: dept, formsemestre_id
Routes: /formsemestre/<int:formsemestre_id>/programme
Exemple d'utilisation: api/formsemestre/1/programme
Résultat: Retourne la liste des Ues, ressources et SAE d'un semestre (json).

Exemple de résultat:

{
  "ues": [
    {
      "type": 0,
      "formation_id": 1,
      "ue_code": "UCOD11",
      "id": 1,
      "ects": 12,
      "acronyme": "RT1.1",
      "is_external": false,
      "numero": 1,
      "code_apogee": "",
      "titre": "Administrer les réseaux et l’Internet",
      "coefficient": 0,
      "semestre_idx": 1,
      "color": "#B80004",
      "ue_id": 1
    },
    ...
  ],
  "ressources": [
    {
      "titre": "Fondamentaux de la programmation",
      "coefficient": 1,
      "module_type": 2,
      "id": 17,
      "ects": null,
      "abbrev": null,
      "ue_id": 3,
      "code": "R107",
      "formation_id": 1,
      "heures_cours": 0,
      "matiere_id": 3,
      "heures_td": 0,
      "semestre_id": 1,
      "heures_tp": 0,
      "numero": 70,
      "code_apogee": "",
      "module_id": 17
    },
    ...
  ],
  "saes": [
    {
      "titre": "Se présenter sur Internet",
      "coefficient": 1,
      "module_type": 3,
      "id": 14,
      "ects": null,
      "abbrev": null,
      "ue_id": 3,
      "code": "SAE14",
      "formation_id": 1,
      "heures_cours": 0,
      "matiere_id": 3,
      "heures_td": 0,
      "semestre_id": 1,
      "heures_tp": 0,
      "numero": 40,
      "code_apogee": "",
      "module_id": 14
    },
    ...
  ]
}

Modules de formation

Les moduleimpl sont les modules d'un semestre, ou les ressources, ou les SAÉs. On peut récupérer soit un module par son id, soit la listes des modules d'un semestre.

moduleimpl

Méthode: GET
Paramètres: moduleimpl_id
Routes: /formations/moduleimpl/<int:moduleimpl_id>
Exemple d'utilisation: /ScoDoc/api/formations/moduleimpl/1
Résultat: Retourne la liste des moduleimpl

Exemple de résultat:

{
  "id": 1,
  "formsemestre_id": 1,
  "computation_expr": null,
  "module_id": 1,
  "responsable_id": 2,
  "moduleimpl_id": 1,
  "ens": [],
  "module": {
    "heures_tp": 0,
    "code_apogee": "",
    "titre": "Initiation aux réseaux informatiques",
    "coefficient": 1,
    "module_type": 2,
    "id": 1,
    "ects": null,
    "abbrev": "Init aux réseaux informatiques",
    "ue_id": 1,
    "code": "R101",
    "formation_id": 1,
    "heures_cours": 0,
    "matiere_id": 1,
    "heures_td": 0,
    "semestre_id": 1,
    "numero": 10,
    "module_id": 1
  }
}

moduleimpls_sem

Méthode: GET
Paramètres: moduleimpl_id
Routes: /formations/moduleimpl/formsemestre/<int:formsemestre_id>/list
Exemple d'utilisation: /ScoDoc/api/formations/moduleimpl/formsemestre/1/list
Résultat: Retourne la liste des moduleimpl d'un semestre

Exemple de résultat:

[
  {
    "id": 1,
    "formsemestre_id": 1,
    "computation_expr": null,
    "module_id": 1,
    "responsable_id": 2,
    "module": {
      "heures_tp": 0,
      "code_apogee": "",
      "titre": "Initiation aux réseaux informatiques",
      "coefficient": 1,
      "module_type": 2,
      "id": 1,
      "ects": null,
      "abbrev": "Init aux réseaux informatiques",
      "ue_id": 1,
      "code": "R101",
      "formation_id": 1,
      "heures_cours": 0,
      "matiere_id": 1,
      "heures_td": 0,
      "semestre_id": 1,
      "numero": 10,
      "module_id": 1
    },
    "moduleimpl_id": 1,
    "ens": []
  }
]

Groupes et partitions

L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieurs partitions (types de groupes). Chaque partition est constituée d'un nombre quelconque de groupes d'étudiants.

partition

Méthode: GET
Paramètres: formsemestre_id
Routes: /ScoDoc/api/partitions/<int:formsemestre_id>
Exemple d'utilisation: /ScoDoc/api/partition/48
Résultat: La liste de toutes les partitions d'un formsemestre.

Exemple de résultat:

[
  {
    "partition_id": 2,
    "id": 2,
    "formsemestre_id": 1,
    "partition_name": "TD",
    "numero": 1,
    "bul_show_rank": false,
    "show_in_lists": true
  },
  {
    "partition_id": 1,
    "id": 1,
    "formsemestre_id": 1,
    "partition_name": null,
    "numero": 0,
    "bul_show_rank": false,
    "show_in_lists": true
  }
]

etud_in_group

Méthode: GET
Paramètres: group_id, etat
Routes: /partitions/groups/<int:group_id> ou /partitions/groups/<int:group_id>/etat/<string:etat>
Exemple d'utilisation: /ScoDoc/api/partitions/groups/1
Résultat: La liste de toutes les partitions d'un formsemestre.

Exemple de résultat:

[
  {
    "etudid": 10,
    "id": 10,
    "dept_id": 1,
    "nom": "BOUTET",
    "prenom": "Marguerite",
    "nom_usuel": "",
    "civilite": "F",
    "date_naissance": null,
    "lieu_naissance": null,
    "dept_naissance": null,
    "nationalite": null,
    "statut": null,
    "boursier": null,
    "photo_filename": null,
    "code_nip": "10",
    "code_ine": "10",
    "scodoc7_id": null,
    "email": "MARGUERITE.BOUTET@example.com",
    "emailperso": null,
    "domicile": null,
    "codepostaldomicile": null,
    "villedomicile": null,
    "paysdomicile": null,
    "telephone": null,
    "telephonemobile": null,
    "fax": null,
    "typeadresse": "domicile",
    "description": null,
    "group_id": 1,
    "etat": "I",
    "civilite_str": "Mme",
    "nom_disp": "BOUTET",
    "nomprenom": "Mme Marguerite BOUTET",
    "ne": "e",
    "email_default": "MARGUERITE.BOUTET@example.com"
  }
]

set_groups
- Méthode: POST
- Paramètres: partition_id, groups_lists, groups_to_delete, groups_to_create
- Routes: /partitions/set_groups/partition/<int:partition_id>/groups/<string:groups_id>/delete/<string:groups_to_delete>/create/<string:groups_to_create>
- Exemple d'utilisation: /ScoDoc/api/partitions/set_groups/partition/1/groups/"A COMPLETER"/delete/"A COMPLETER"/create/"A COMPLETER"
- Résultat: Set les groups.

Bulletins de notes

evaluations

Méthode: GET
Paramètres: moduleimpl_id
Routes: /evaluations/<int:moduleimpl_id>
Exemple d'utilisation: /ScoDoc/api/evaluations/1
Résultat: Retourne la liste des évaluations à partir de l'id d'un moduleimpl

Exemple de résultat:

[
  {
    "moduleimpl_id": 1,
    "jour": "20/04/2022",
    "heure_debut": "08h00",
    "description": "eval1",
    "coefficient": 1,
    "publish_incomplete": false,
    "numero": 0,
    "id": 1,
    "heure_fin": "09h00",
    "note_max": 20,
    "visibulletin": true,
    "evaluation_type": 0,
    "evaluation_id": 1,
    "jouriso": "2022-04-20",
    "duree": "1h",
    "descrheure": " de 08h00 à 09h00",
    "matin": 1,
    "apresmidi": 0
  }
]

evaluation_notes

Méthode: GET
Paramètres: evaluation_id
Routes: /evaluations/eval_notes/<int:evaluation_id>
Exemple d'utilisation: /ScoDoc/api/evaluations/eval_notes/1
Résultat: Retourne la liste des notes à partir de l'id d'une évaluation donnée

Exemple de résultat:

{
  "1": {
    "id": 1,
    "etudid": 10,
    "evaluation_id": 1,
    "value": 15,
    "comment": "",
    "date": "Wed, 20 Apr 2022 06:49:05 GMT",
    "uid": 2
  },
  "2": {
    "id": 2,
    "etudid": 1,
    "evaluation_id": 1,
    "value": 12,
    "comment": "",
    "date": "Wed, 20 Apr 2022 06:49:06 GMT",
    "uid": 2
  }
}

Absences

Remarques, les dates sont au format iso yyyy-mm-dd. Les dates de fin ne sont pas incluses. Et demi_journee= 2 si journée complète, =1 si uniquement le matin, =0 si uniquement l'après-midi.

absences

Méthode: GET
Paramètres: etudid, nip, ine
Routes: /absences/etudid/<int:etudid> ou /absences/nip/<int:nip> ou /absences/ine/<int:ine>
Exemple d'utilisation: /ScoDoc/api/absences/ine/1
Résultat: Retourne la liste des absences d'un étudiant donné

Exemple de résultat:

[
  {
    "jour": "2022-04-15",
    "matin": true,
    "estabs": true,
    "estjust": true,
    "description": "",
    "begin": "2022-04-15 08:00:00",
    "end": "2022-04-15 11:59:59"
  },
  {
    "jour": "2022-04-15",
    "matin": false,
    "estabs": true,
    "estjust": false,
    "description": "",
    "begin": "2022-04-15 12:00:00",
    "end": "2022-04-15 17:59:59"
  }
]

absences_just

Méthode: GET
Paramètres: etudid, nip, ine
Routes: /absences/etudid/<int:etudid>/just ou /absences/nip/<int:nip>/just ou /absences/ine/<int:ine>/just
Exemple d'utilisation: /ScoDoc/api/absences/ine/1/just
Résultat: Retourne la liste des absences justifiées d'un étudiant donné

Exemple de résultat:

[
  {
    "jour": "2022-04-15",
    "matin": true,
    "estabs": true,
    "estjust": true,
    "description": "",
    "begin": "2022-04-15 08:00:00",
    "end": "2022-04-15 11:59:59"
  },
  {
    "jour": "2022-04-15",
    "matin": false,
    "estabs": true,
    "estjust": true,
    "description": "",
    "begin": "2022-04-15 12:00:00",
    "end": "2022-04-15 17:59:59"
  }
]

abs_groupe_etat
- Méthode: GET
- Paramètres: group_ids, date_debut, date_fin, with_boursier=True, format=html
- Routes: /absences/abs_group_etat/<int:group_id> ou /absences/abs_group_etat/group_id/<in:group_id>/date_debut/<date:date_debut>/date_fin/<date:date_fin>
- Exemple d'utilisation: /ScoDoc/api/absences/abs_group_etat/1
- Résultat: Liste des absences d'un ou plusieurs groupes entre deux dates.
- Exemple de résultat:
```
XXX A COMPLETER
```

Jury

jury_preparation
- Méthode: GET
- Paramètres: formsemestre_id
- Routes: /jury/formsemestre/<int:formsemestre_id>/preparation_jury
- Exemple d'utilisation: /ScoDoc/api/jury/formsemestre/1/preparation_jury
- Résultat: Retourne la feuille de préparation du jury
- Exemple de résultat:
```
XXX A COMPLETER
```
jury_decisions
- Méthode: GET
- Paramètres: formsemestre_id
- Routes: /jury/formsemestre/<int:formsemestre_id>/decisions_jury
- Exemple d'utilisation: /ScoDoc/api/jury/formsemestre/1/decisions_jury
- Résultat: Retourne les décisions du jury suivant un formsemestre donné
- Exemple de résultat:
```
XXX A COMPLETER
```

Logos

liste des logos globaux
- Méthode: GET
- Paramètres: format (json, xml), json par défaut
- Route : /ScoDoc/api/logos
- Exemple d'utilisation : /ScoDoc/api/logos?format=xml
- Résultat : Liste des logos définis pour le site scodoc.
- Exemple de résultat: ['header', 'footer', 'custom']
récupération d'un logo global
- Méthode: GET
- Paramètres : Aucun
- Route: /ScoDoc/api/logos/<string:nom>
- Exemple d'utilisation : /ScoDoc/api/logos/header
- Résultat : l'image (format png ou jpg)
logo d'un département
- Méthode: GET
- Paramètres: format (json, xml)
- Route : /ScoDoc/api/departements/<string:dept>/logos
- Exemple d'utilisation : /ScoDoc/api/MMI/logos
- Résultat : Liste des logos définis pour le département visé.
- Exemple de résultat: ['footer', 'signature', 'universite']
récupération d'un logo global
- Méthode: GET
- Paramètres : Aucun
- Route: /ScoDoc/api/departements/<string:dept>/logos/<string:nom>
- Exemple d'utilisation: /ScoDoc/api/departements/MMI/logos/header
- Résultat : l'image (format png ou jpg)

En savoir plus

Voir exemples d'utilisation de l'API en Python, dans tests/api/.

Fonctions de l'API ScoDoc 7 portées en ScoDoc 9

L'ancienne API ScoDoc 7 est décrite ici: ScoDocAPI

Afin de garantir l'interopérabilité avec les clients ScoDoc 7 (ENT, etc), les fonctions suivantes sont disponibles avec le mécanisme d'authentification basique de ScoDoc 7. Elles sont considérées comme obsolètes ("deprecated") et disparaitront en juillet 2022.

Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès.

Absences/XMLgetBilletsEtud (deviendra api/absences/billets/etud/ etudid>)
Absences/AddBilletAbsence (deviendra api/absences/billet/add)
Absences/XMLgetAbsEtud (deviendra api/absences/ etudid>, en json)
Notes/evaluation_listenotes (non existante en ScoDoc9, trop complexe)
Notes/formsemestre_id (deviendra api/formsemestre)
Notes/formsemestre_bulletinetud (deviendra api/etud/<etudid>/bul/<formsemestre_id>)
Notes/XMLgetFormsemestres (non existante en ScoDoc9, redondant avec api/formsemestre ?)
etud_info ou XMLgetEtudInfos ou Absences/XMLgetEtudInfos ou Notes/XMLgetEtudInfos (deviendra /api/etud/<etudid>)
groups_view (deviendra groups)

Les routes ci-dessus s'entendent à partir de l'URL de base de votre ScoDoc, c'est à dire https://votre.site.fr/ScoDoc/<dept>/Scolarite/, et répondent en GET et en POST.

Note:

Absences/listeBillets est un formulaire et ne fait pas partie de l'API.

49 KiB Raw Blame History Unescape Escape

API pour ScoDoc 9

Configuration de ScoDoc pour utiliser l'API

Fonctions d'API ScoDoc 9 (work in progress)

Accès à l'API REST

Authentification

Codes HTTP

Note sur les identifiants de sessions

Départements

Etudiants

Programmes de formations

Semestres de formation

Modules de formation

Groupes et partitions

Bulletins de notes

Absences

Jury

Logos

En savoir plus

Fonctions de l'API ScoDoc 7 portées en ScoDoc 9

49 KiB

Raw Blame History