Documentation
|
API (interfaçage logiciel)Fonctionnalité expérimentale encore en développement. Introduction Une API est une interface permettant à des applications informatiques de se connecter afin d’échanger des données ou des fonctionnalités. Une telle API a été développée dans SACoche afin de répondre à une demande d’interfaçage avec l’application Papillon. Utilisateurs - Mise en place
Actuellement, les services proposés ne concernent que le profil
Côté SACoche, avec un compte élève, se rendre dans le menu Du côté de l’application tierce, l’utilisateur doit renseigner ces deux valeurs (URL et jeton). Développeurs - Généralités techniques
Les paramètres doivent être passés en POST.
Les réponses seront au format JSON (sauf plantage serveur non intercepté). La structure de la réponse est toujours selon ce modèle :
{
"code" : number,
"message" : string,
"data" : array|string|null
}
Les codes de retour possibles sont :
Développeurs - ConnexionLes paramètres à envoyer sont :
{
"service" : "login",
"jeton" : string // celui fourni par SACoche à l’utilisateur
}
Les principaux retours possibles sont :
{
"code" : 200,
"message" : "Connexion réussie.",
"data" : {
"nom" : string,
"prenom" : string,
"profil" : string, // "élève"
"structure" : string // dénomination de l’établissement
}
}
{
"code" : 100,
"message" : "Connexion déjà établie ; se déconnecter ou appeler le service souhaité.",
"data" : null
}
{
"code" : 400,
"message" : string, // jeton manquant ou invalide ou incohérent ou tout autre problème de connexion
"data" : null
}
Développeurs - DéconnexionLes paramètres à envoyer sont :
{
"service" : "logout",
"jeton" : string // celui fourni par SACoche à l’utilisateur
}
Il n’y a pas d’erreur émise si aucune session existante n’est trouvée.
{
"code" : 200,
"message" : "Déconnexion effectuée.",
"data" : null
}
Développeurs - Lister les évaluationsLes paramètres à envoyer sont :
{
"service" : "lister_evaluations",
"jeton" : string // celui fourni par SACoche à l’utilisateur
"date_debut" : "JJ/MM/AAAA", // facultatif, date de début d’année scolaire sinon
"date_fin" : "JJ/MM/AAAA" // facultatif, date de fin d’année scolaire sinon
}
Les évaluations retournées sont classées de la plus récente à la plus ancienne.
{
"code" : 200,
"message" : "{n} évaluation(s) trouvée(s)",
"data" : {
0 : {
"id" : integer, // identifiant du devoir
"date" : "JJ/MM/AAAA", // date du devoir
"professeur" : string, // nom de l’enseignant
"description" : string, // intitulé du devoir
"rempli" : string, // indicateur de saisie des notes : { oui | non | partiel }
"enonce" : string, // lien éventuel vers un document de sujet
"corrige" : string // lien éventuel vers un document de correction
},
1 : {
… // idem pour les devoirs suivants
}
}
}
{
"code" : 400,
"message" : string, // paramètre invalide ou incohérent, aucune évaluation trouvée…
"data" : null
}
Développeurs - Voir les saisies à une évaluationLes paramètres à envoyer sont :
{
"service" : "voir_saisies_evaluation",
"jeton" : string // celui fourni par SACoche à l’utilisateur
"devoir_id" : integer // identifiant du devoir
}
Les principaux retours possibles sont :
{
"code" : 200,
"message" : string, // info sur le devoir (date, enseignant, intitulé)
"data" : {
"item" : {
item_id_1 : {
"note" : string|null, // { 1 | 2 | 3 | 4 | 5 | 6 | AB | DI | NE | NF | NN | NR }
"reference" : string, // référence de l’item
"nom" : string, // intitulé de l’item
"information" : string, // commentaire éventuel associé à l’item dans le référentiel
"lien" : string // lien de remédiation éventuel associé à l’item
},
item_id_2 : {
… // idem pour les autres items
}
},
"commentaire_ecrit" : string|null, // commentaire écrit éventuel
"commentaire_audio" : string|null, // commentaire audio éventuel sous forme d’un lien
"legende" {
"notes" : {
"1" : {
"sigle" : string, // par exemple "VV"…
"image" : string, // lien vers image 20px sur 10px
"texte" : string // par exemple "Très bonne maîtrise"…
},
"2" : {
… // idem pour les notes suivantes ainsi que les éventuels codes neutres
}
}
}
}
}
{
"code" : 400,
"message" : string, // paramètre invalide ou incohérent, devoir non trouvé…
"data" : null
}
Développeurs - Test de l’API
L’API peut être testée avec le code suivant (remplacer chaque occurrence de
<html>
<body>
<h1>Test API SACoche</h1>
<form action="https://ADRESSE-DE-SACOCHE/api.php" method="post" target="_blank">
<fieldset>
<legend>Connexion</legend>
<input name="service" value="login" type="hidden">
<label for="jeton">Jeton : </label><input name="jeton" id="jeton" value="" size="75" type="text" placeholder="Y reporter la valeur fournie par SACoche">
<input value="✅" type="submit">
</fieldset>
</form>
<form action="https://ADRESSE-DE-SACOCHE/api.php" method="post" target="_blank">
<fieldset>
<legend>Déconnexion</legend>
<input name="service" value="logout" type="hidden">
<label for="jeton">Jeton : </label><input name="jeton" id="jeton" value="" size="75" type="text" placeholder="Y reporter la valeur fournie par SACoche">
<input value="✅" type="submit">
</fieldset>
</form>
<form action="https://ADRESSE-DE-SACOCHE/api.php" method="post" target="_blank">
<fieldset>
<legend>Lister les évaluations</legend>
<input name="service" value="lister_evaluations" type="hidden">
<label for="jeton">Jeton : </label><input name="jeton" id="jeton" value="" size="75" type="text" placeholder="Y reporter la valeur fournie par SACoche"><br>
<label for="date_debut">Date de début : </label><input name="date_debut" id="date_debut" value="" size="10" type="text" placeholder="JJ/MM/AAAA">
<label for="date_fin">Date de fin : </label><input name="date_fin" id="date_fin" value="" size="10" type="text" placeholder="JJ/MM/AAAA">
<input value="✅" type="submit">
</fieldset>
</form>
<form action="https://ADRESSE-DE-SACOCHE/api.php" method="post" target="_blank">
<fieldset>
<legend>Voir les saisies à une évaluation</legend>
<input name="service" value="voir_saisies_evaluation" type="hidden">
<label for="jeton">Jeton : </label><input name="jeton" id="jeton" value="" size="75" type="text" placeholder="Y reporter la valeur fournie par SACoche"><br>
<label for="devoir_id">Identifiant du devoir : </label><input name="devoir_id" id="devoir_id" value="" size="8" type="number">
<input value="✅" type="submit">
</fieldset>
</form>
</body>
</html>
|
élève (même si la connexion / déconnexion fonctionnera pour tous les profils).