DocScoDocPE/ScoDoc9API.md at af4525989a275a04bd63f89939652e7db00d4a43

Jean-Marie PLACE af4525989a v1

2022-07-25 11:57:43 +02:00

51 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
...

Si vous êtes intéressé par le développement, voir la section sur les tests unitaires de l'API.

Essais avec HTTPie

HTTPie est un client universel livre et gratuit très commode, disponible pour Windows, Linux, en ligne de commande ou interface graphique.

Exemple d'utilisation en ligne de commande et interroger votre ScoDoc pour obtenir la liste des départements:

http -a USER:PASSWORD POST  'http://localhost:5000/ScoDoc/api/tokens'

Qui affiche:

HTTP/1.1 200 OK
Content-Length: 50
Content-Type: application/json
Date: Thu, 05 May 2022 04:29:33 GMT

{
    "token": "jS7iVl1234cRDzboAfO5xseE0Ain6Zyz"
}

(remplacer USER:PASSWORD par les identifiants de votre utilisateur et adapter l'URL qui est ici celle d'un client local sur le serveur de test).

Avec ce jeton (token), on peut interroger le serveur:

http GET http://localhost:5000/ScoDoc/api/departements "Authorization:Bearer jS7iVlH1234cRDzboAfO5xseE0Ain6Zyz"

qui affiche par exemple:

HTTP/1.1 200 OK
Content-Length: 151
Content-Type: application/json
Date: Thu, 05 May 2022 05:21:33 GMT

[
    {
        "acronym": "TAPI",
        "date_creation": "Wed, 04 May 2022 21:09:25 GMT",
        "description": null,
        "id": 1,
        "visible": true
    }
]

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, voir plus haut pour la ême chose avec la commande http):

curl -u user_name:password --request POST https://SERVEUR/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 le serveur ScoDoc.

200 : OK.
400 : Paramètre manquant, ou valeur incorrecte.
401 : Authentification nécessaire. (jeton non précisé ou invalide)
403 : Action non autorisée pour l'utilisateur associé au jeton
404 : Page inaccessible: URL inconnue ou paramètre (id) invalide
406 : Le JSON indiqué en données POST n'est pas valide.
500 : Erreur inconnue, contactez-nous.

Départements

`departements_ids`

Méthode: GET
Routes: /departements_ids
Résultat: Liste des id départements (visibles ou non).
Exemple de résultat:
```
[ 1888, 999, 165 ]
```

`departements`

Méthode: GET
Routes: /departements
Exemple d'utilisation: /api/departements
Résultat: Liste des tous les départements (visibles ou non).
Exemple de résultat:
```
[
  { un département }
  ...
]
```

`departement`

Méthode: GET
Routes:
- /departement/id/<int:dept_id>
- /departement/<string:dept>
Résultat: Un département

Exemple de résultat:

{
    "id": 1,
    "acronym": "TAPI",
    "description": null,
    "visible": true,
    "date_creation": "Fri, 15 Apr 2022 12:19:28 GMT"
},

Étudiants d'un département

Méthode: GET
Paramètres: dept, formsemestre_id
Routes:
- /departement/id/<int:dept_id>/etudiants
- /departement/<string:dept>/etudiants
Exemple d'utilisation: /api/departement/MMI/etudiants
Résultat: liste tous les étudiants d'un département. On peut spécifier l'acronyme du département ("MMI") ou son id (un entier). Attention, la liste peut être longue: requête coûteuse à éviter.

Exemple de résultat:

[
  {
        "civilite": "M", // M, F ou X
        "ine": "7899X61616",
        "nip": "F6777H88",
        "date_naissance": null,
        "email": "toto@toto.fr",
        "emailperso": null,
        "etudid": 18,
        "nom": "MOREL", // en majuscules
        "prenom": "JACQUES"
  },
  ...
]

Formsemestre d'un département

Méthode: GET
Paramètres: dept
Routes:
- /departement/id/<int:dept_id>/formsemestres_ids
- /departement/<string:dept>/formsemestres_ids
Exemple d'utilisation: /api/departement/MMI/formsemestres_ids
Résultat: Liste des id des formsemestres d'un département donné.
Exemple de résultat: [ 28, 99, 3 ]

Formsemestre courants d'un département

Méthode: GET
Paramètres: dept
Routes:
- /departement/id/<int:dept_id>/formsemestres_courants
- /departement/<string:dept>/formsemestres_courants
Exemple d'utilisation: /api/departement/MMI/formsemestres_courants
Résultat: Liste des id des formsemestres en cours d'un département donné.
Exemple de résultat: [ 28, 99 ]

Semestres

Formsemestre

Méthode: GET
Paramètres: dept
Routes:
- /formsemestre/<int:formsemestre_id>
Exemple d'utilisation: /api/formsemestre/1
Résultat: Données d'un formsemestre spécifié par son id.
Exemple de résultat:

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

Formsemestres

Méthode: GET
Paramètres: dept
Routes:
- /departement/id/<int:dept_id>/formsemestres_ids
- /departement/<string:dept>/formsemestres_ids
Exemple d'utilisation: /api/departement/MMI/formsemestres_ids
Résultat: Liste des id des formsemestres d'un département donné.
Exemple de résultat:

Formsemestres en cours

Méthode: GET
Paramètres: dept
Routes:
- /departement/id/<int:dept_id>/formsemestres_courants
- /departement/<string:dept>/formsemestres_courants
Exemple d'utilisation: /api/departement/MMI/formsemestres_courants
Résultat: Liste des formsemestres en cours d'un département donné (date du jour dans la période couverte par le formsemestre,tous départements, dans tous les départements où l'utilisateur à le rôle APIView ou ScoView)

Exemple de résultat:

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

Le titreest celui donné par l'utilisateur dans le formsemestre, tandis que le titre_formation est l'acronyme de la formation (défini dans son programme pédagogique).

Étudiants

`etudiants_courant`

Méthode: GET
Routes:
- /etudiants/courant
- /etudiants/courant/long
Exemple d'utilisation: /api/etudiants/courant
Résultat: Liste des étudiants inscrits dans un formsemestre actuellement en cours. Avec /long, donne tous les attributs de l'étudiants (plus lent).

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/<string:nip> ou /etudiant/ine/<string:ine>
Exemple d'utilisation: /api/etudiant/nip/1
Résultat: Retourne les informations sur l'étudiant correspondant à l'id passé en paramètres. Les codes INE et NIP sont uniques au sein d'un département. Si plusieurs objets étudiant ont le même code, on ramène le plus récemment inscrit.

Exemple de résultat:

{
  "civilite": "X",
  "code_ine": "1",
  "code_nip": "1",
  "date_naissance": "",
  "dept_id": 1,
  "dept_acronym": "TAPI",
  "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": ""
}

`etudiants`

Méthode: GET
Paramètres: etudid, nip, ine
Routes: /etudiants/etudid/<int:etudid> ou /etudiants/nip/<string:nip> ou /etudiants/ine/<string:ine>
Exemple d'utilisation: /api/etudiants/nip/1
Résultat: Info sur le ou les étudiants correspondants. Comme /etudiant mais renvoie toujours une liste. Si non trouvé, liste vide, pas d'erreur. Dans 99% des cas, la liste contient un seul étudiant, mais si l'étudiant a été inscrit dans plusieurs départements, on a plusieurs objets (1 par dept.).
Exemple de résultat: [ { "civilite": "X", "code_ine": "1", "code_nip": "1", "date_naissance": "", "dept_id": 1, "dept_acronym": "TAPI", "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": "" } ]

Cursus

`etudiant_formsemestres`

Méthode: GET
Paramètres: etudid, nip, ine
Routes: : /etudiant/etudid/<int:etudid>/formsemestres ou /etudiant/nip/<string:nip>/formsemestres ou /etudiant/ine/<string: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"
  },
  ...
]

Bulletin

`etudiant_bulletin_semestre`

Méthode: GET
Paramètres: formsemestre_id, etudid, nip, ine
Routes: /etudiant/etudid/<int:etudid>/formsemestre/<int:formsemestre_id>/bulletin[/format][/pdf] ou /etudiant/nip/<string:nip>/formsemestre/<int:formsemestre_id>/bulletin[/format][/pdf] ou /etudiant/ine/<string:ine>/formsemestre/<int:formsemestre_id>/bulletin[/format][/pdf]

On peut spécifier le format: longou short, et indiquer si l'on veut le bulletin PDF.

Exemple d'utilisation: /etudiant/nip/1/formsemestre/1/bulletin
Résultat: Bulletin de l'étudiant dans le formsemestre. Deux versions disponibles long et short (par défaut long ajoutez /short pour la version plus courte).

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/<string:nip>/semestre/<int:formsemestre_id>/groups ou /etudiant/ine/<string: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

`formation`

Méthode: GET
Paramètres: formation_id
Routes: /formation/<int:formation_id>
Exemple d'utilisation: /ScoDoc/api/formation/1
Résultat: Retourne la formation d'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
}

`formations_ids`

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

`formations`

Méthode: GET
Routes: /formations
Exemple d'utilisation: /ScoDoc/api/formations
Résultat: Retourne la liste de toutes les formations (tous départements)

Export programme

`formation_export`

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

Exemple de résultat:

{
  "id": 1,
  "acronyme": "BUT R&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"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Référentiel de compétences

`referentiel_competences`

Méthode: GET
Paramètres: formation_id
Routes: /formation/<int:formation_id>/referentiel_competences
Exemple d'utilisation: api/formation/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 ?

Formsemestres

Les sessions de formation (qu'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:

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

`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:

[ { formsemestre comme ci-dessus }, ... ]

Note sur les identifiants de formsemestre

Le session_id peut être utilisé pour identifier de façon prévisible et (presque) unique un formsemestre) 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...) (acronyme 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) dans la "formation" (le 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)

Étudiants inscrits et bulletins

etudiants

Méthode: GET
Paramètres: formsemestre_id, etat (par défaut égal à "I" pour les étudiants inscrits)
Routes: /formsemestre/<int:formsemestre_id>/etudiants XXX voir si filtrage par état (dem, def, ...)
Résultat: les étudiants inscrits à ce semestres XXX préciser état (DEM, DEF))

* `bulletins`

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

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
        }
      }
    }
  }
]

etat_evals

Méthode: GET
Paramètres: formsemestre_id
Routes: /formsemestre/<int:formsemestre_id>/etat_evals
Exemple d'utilisation: /ScoDoc/api/formsemestre/1/etat_evals
Résultat: Retourne les informations sur l'état des évaluations d'un semestre donnée

Exemple de résultat:

{
  "RT1.1": [
    {
      "id": 1,
      "titre": "Initiation aux réseaux informatiques",
      "evaluations": [
        {
          "id": 1,
          "description": null,
          "datetime_epreuve": null,
          "heure_fin": "09:00:00",
          "comptee": "oui",
          "inscrits": 16,
          "manquantes": 0,
          "ABS": 0,
          "ATT": 0,
          "EXC": 0,
          "saisie_notes": {
            "datetime_debut": "2021-09-11T00:00:00+02:00",
            "datetime_fin": "2022-08-25T00:00:00+02:00",
            "datetime_mediane": "2022-03-19T00:00:00+01:00"
          }
        },
        {
          "id": 22,
          "description": null,
          "datetime_epreuve": "2021-08-11T00:00:00+02:00",
          "heure_fin": "08:00:00",
          "comptee": "oui",
          "inscrits": 16,
          "manquantes": 0,
          "ABS": 0,
          "ATT": 0,
          "EXC": 0,
          "saisie_notes": {
            "datetime_debut": "2021-09-11T00:00:00+02:00",
            "datetime_fin": "2022-08-25T00:00:00+02:00",
            "datetime_mediane": "2022-03-19T00:00:00+01:00"
          }
        },
      ]
    },
  ]
}

`jury` (non implémentée)

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 d'un formsemestre

UE et modules

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

Exemple de résultat:

{
  "ues": [
    {
      "type": 0,
      "formation_id": 1,
      "ue_code": "UCOD11",
      "id": 1,
      "ects": 12.0,
      "acronyme": "RT1.1",
      "is_external": false,
      "numero": 1,
      "code_apogee": "",
      "titre": "Administrer les r\u00e9seaux et l\u2019Internet",
      "coefficient": 0.0,
      "semestre_idx": 1,
      "color": "#B80004",
      "ue_id": 1
    },
    ...
  ],
  "ressources": [
    {
    "ens": [ 10, 18 ],
    "formsemestre_id": 1,
    "id": 15,
    "module": {
        "abbrev": "Programmer",
        "code": "SAE15",
        "code_apogee": "V7GOP",
        "coefficient": 1.0,
        "formation_id": 1,
        "heures_cours": 0.0,
        "heures_td": 0.0,
        "heures_tp": 0.0,
        "id": 15,
        "matiere_id": 3,
        "module_id": 15,
        "module_type": 3,
        "numero": 50,
        "semestre_id": 1,
        "titre": "Programmer en Python",
        "ue_id": 3
    },
    "module_id": 15,
    "moduleimpl_id": 15,
    "responsable_id": 2
  },
    ...
  ],
  "saes": [
    {
      ...
    },
    ...
  ],
  "modules" : [ ... les modules qui ne sont ni des SAEs ni des ressources ... ]
}

Module d'un formsemestre

Le moduleimpl est la mise en place d'un module dans un formsemestre (avec son responsable et ses enseignants).

`moduleimpl`

Méthode: GET
Paramètres: moduleimpl_id
Routes: /formation/moduleimpl/<int:moduleimpl_id>
Exemple d'utilisation: /ScoDoc/api/formation/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
  }
}

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: /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
  }
]

`groups`

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: Retourne la liste des étudiants dans un groupe.
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"
      }
    ]

Évaluations

`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 (quel que soit leur statut).

Exemple de résultat:

[
  {
    "apresmidi": 0
    "coefficient": 1,
    "description": "Compte-rendu de TP 2",
    'date_debut': '2022-05-13T11:30:00',
    'date_fin': '2022-05-13T12:30:00',
    "evaluation_id": 1,
    "evaluation_type": 0,
    "id": 1,
    "jour": "13/05/2022",
    "matin": 1,
    "moduleimpl_id": 1,
    "note_max": 20,
    "numero": 0,
    "publish_incomplete": false,
    "poids" : {1896: 0.0, 1897: 2.3, 1898: 4.2},
    "visibulletin": true,
  }
]

`evaluations/notes`

Méthode: GET
Paramètres: evaluation_id
Routes: /evaluations/eval_notes/<int:evaluation_id>
Exemple d'utilisation: /ScoDoc/api/evaluations/notes/1
Résultat: Retourne la liste des notes d'une évaluation
Exemple de résultat: XXX à revoir (à spécifier/reprendre implémentation XXX was eval_notes)

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>
Exemple d'utilisation: /ScoDoc/api/absences/etudid/123456
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": "Retard bus",
    "begin": "2022-04-15 08:00:00",
    "end": "2022-04-15 11:59:59"
  },
  {
    ...
  }
]

`absences/just`

Méthode: GET
Paramètres: etudid
Routes: /absences/etudid/<int:etudid>/just
Exemple d'utilisation: /ScoDoc/api/absences/etudid/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": "Retard bus",
    "begin": "2022-04-15 08:00:00",
    "end": "2022-04-15 11:59:59"
  },
  {
    ...
  }
]

`abs_groupe_etat`

Méthode: GET
Paramètres: group_ids, date_debut, date_fin,
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 groupe entre deux dates.
Exemple de résultat:
```
XXX A COMPLETER XXX with_boursier ??
```
XXX ajouter méthode(s) de set abs ```

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 noms des logos définis pour le site scodoc.
Exemple de résultat: ['header', 'footer', 'custom']

XXX vérifier si on supporte XML et pour qui ?

`récupération d'un logo global`

Méthode: GET
Paramètres : Aucun
Route: /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 : /departements/<string:dept>/logos
Exemple d'utilisation : /ScoDoc/api/departements/MMI/logos
Résultat : Liste des noms 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: /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.

51 KiB Raw Blame History Unescape Escape

API pour ScoDoc 9

Configuration de ScoDoc pour utiliser l'API

Essais avec HTTPie

Fonctions d'API ScoDoc 9 (work in progress)

Accès à l'API REST

Authentification

Codes HTTP

Départements

departements_ids

departements

departement

Étudiants d'un département

Formsemestre d'un département

Formsemestre courants d'un département

Semestres

Formsemestre

Formsemestres

Formsemestres en cours

Étudiants

etudiants_courant

etudiant

etudiants

Cursus

etudiant_formsemestres

Bulletin

etudiant_bulletin_semestre

etudiant_groups

Programmes de formations

formation

formations_ids

formations

Export programme

formation_export

Référentiel de compétences

referentiel_competences

Formsemestres

formsemestre

formsemestre_apo

Note sur les identifiants de formsemestre

Étudiants inscrits et bulletins

etudiants

* bulletins

etat_evals

jury (non implémentée)

Programme d'un formsemestre

UE et modules

Module d'un formsemestre

moduleimpl

Groupes et partitions

partition

groups

Évaluations

evaluations

evaluations/notes

Absences

absences

absences/just

abs_groupe_etat

Jury

jury_preparation

jury_decisions

Logos

liste des logos globaux

récupération d'un logo global

logo d'un département

récupération d'un logo global

En savoir plus

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

51 KiB

Raw Blame History

`departements_ids`

`departements`

`departement`

`etudiants_courant`

`etudiant`

`etudiants`

`etudiant_formsemestres`

`etudiant_bulletin_semestre`

`etudiant_groups`

`formation`

`formations_ids`

`formations`

`formation_export`

`referentiel_competences`

`formsemestre`

`formsemestre_apo`

* `bulletins`

`jury` (non implémentée)

`moduleimpl`

`partition`

`groups`

`evaluations`

`evaluations/notes`

`absences`

`absences/just`

`abs_groupe_etat`

`jury_preparation`

`jury_decisions`

`liste des logos globaux`

`récupération d'un logo global`

`logo d'un département`

`récupération d'un logo global`