CETTE DOCUMENTATION N'EST PLUS à JOUR !
Documentation générale des API proposées sur "notes"

Introduction

Pour des raisons de sécurité, le serveur Scodoc qui gère les notes n'est pas accessible en ligne, il est nécessaire d'être sur une liste blanche de postes depuis l'université ou être un utilisateur autorisé en utilisant le VPN de l'université.

Le serveur "notes" est une passerelle sécurisé entre Scodoc et Internet. Ce serveur propose une interface HTML / CSS aux étudiants leurs permettant de consulter leurs notes et moyennes. Les enseignants peuvent consulter les notes d'un étudiant choisi.

Pour des raisons de sécurité, le lien entre Scodoc et le serveur "notes" est en lecture seule.

L'interface HTML / CSS utilise différents services proposés sur le serveur "notes". Ces services sont accessibles via une API REST.

Communication

L'accès à l'API se fait via des requêtes GET : 

https://urlDuServeur.fr/services/data.php?q={requête}&autresParamètres

q étant la requête.
En fonction de cette requête, d'autres paramètres complémentaires peuvent être transmis.

Pour la suite, l'URL du serveur sera https://notes.iutmulhouse.uha.fr

Il est possible d'utiliser fetch en JS ou via du CURL en PHP par exemple.
L'ensemble des réponses se fait au format JSON. 

/**************************/
/* Exemple de traitement de la communication */
/**************************/
function fetchData(query){
	return fetch("services/data.php?q="+query, {"method": "post"})
	.then(res => { return res.json() })
	.then(function(data) {
		if(data.redirect){
			// Utilisateur non authentifié, redirection vers une page d'authentification pour le CAS.
			// Passage de l'URL courant au CAS pour redirection après authentification.
			// Voir la section "Authentification aux services".
			window.location.href = data.redirect + "?href="+encodeURIComponent(window.location.href); 
		}
		if(data.erreur){
			// Il y a une erreur pour la récupération des données - affichage d'un message explicatif.
			document.querySelector(".zoneErreur").innerHTML = data.erreur;
		}else{
			return data;
		}
	})
}

Gestion des erreurs

En cas d'erreur, la réponse sera : 

{
	"erreur": "Message d'erreur"
}

Ces messages d'erreurs comportent des indications sur comment résoudre le problème.
Il peut par exemple y avoir un problème d'import du numéro d'étudiant dans Scodoc, il faut supprimer le .0 qui se trouve à la fin.

Utilisation d'un jeton JWT

Un jeton JWT peut être passé en paramètre POST 'token' pour autoriser l'accès aux services. Ce jeton est à transmettre à chaque requête lors de la communication entre serveurs (et uniquement dans ce cas).
Voir la section "Authentification aux services".

API : Authentification aux services

Permet de vérifier et le cas échéant de s'authentifier au CAS de l'UHA.
Il y a deux manières de s'authentifier, soit avec le CAS UHA, soit avec un jeton JWT, ce jeton est à générer au préalable par l'administrateur.

L'utilisation du CAS est à privilégier pour une interface HTML / CSS (uniquement sur le serveur où l'authentification se fait).
Le jeton JWT est à utiliser lors d'une communication inter-serveur en le passant en paramètre POST 'token'.
Il est également possible d'utiliser le jeton pour montrer le service à une personne n'étant pas dans le CAS - il faut de manière générale éviter d'utiliser cette méthode dans une fonctionnement récurrent et si c'est le cas définir une durée de vie de jeton courte.

!!! Attention, ce jeton est personnel et permet d'accéder aux services. Il ne doit en aucun cas être public !!!

Query

donnéesAuthentification

Exemple

https://notes.iutmulhouse.uha.fr/services/data.php?q=donnéesAuthentification

Entrée

Pas de paramètre d'entrée.

Sortie

{
	"redirect": "URL vers le CAS"
}

ou

{
	"session": "mail de la personne",
	"statut" : "etudiant" | "personnel" | "none" // none étant identifié à l'UHA mais inconnu à l'IUT
}

API : Liste étudiants de l'IUT

Cette ressource est limitée aux utilisateurs avec un statut "personnel".

Récupère la liste de tous les étudiants inscrits dans le LDAP pour l'IUT.

Pour le moment, cette liste est mise à jour manuellement - si un étudiant n'y est pas listé, veuillez contacter l'administrateur pour une mise à jour et vérification.

Query

listeEtudiants

Exemple

https://notes.iutmulhouse.uha.fr/services/data.php?q=listeEtudiants

Entrée

Pas de paramètre d'entrée.

Sortie

[
	"etudiant1@uha.fr",
	"etudiant2@uha.fr", 
	etc.
]

API : Liste des semestres d'un étudiant

Liste les identifiants de semestres qu'un étudiant a suivi.

Si l'utilisateur est un "personnel", il peut demander les semestres de n'importe quel étudiant.

Query

semestresEtudiant

Exemples

https://notes.iutmulhouse.uha.fr/services/data.php?q=semestresEtudiant&etudiant=alexandre.aab@uha.fr
https://notes.iutmulhouse.uha.fr/services/data.php?q=semestresEtudiant

Entrée

// Ce paramètre n'est utilisable que si l'utilisateur est reconnu comme "personnel".
[Optionnel] etudiant : identifiant de l'étudiant (adresse mail) sinon, l'adresse de session est automatiquement utilisé.

Sortie

// Identifiant Scodoc des semestres - utile pour d'autres requêtes.
// Par ordre chonologique.
[
	"SEM8871", 
	"SEM8833", 
	etc.
]

API : Relevé de notes d'un étudiant

Renvoie les données du relevé de notes d'un étudiant

Si l'utilisateur est un "personnel", il peut demander les semestres de n'importe quel étudiant.

Query

relevéEtudiant

Exemples

https://notes.iutmulhouse.uha.fr/services/data.php?q=relevéEtudiant&semestre=SEM8871&etudiant=alexandre.aab@uha.fr
https://notes.iutmulhouse.uha.fr/services/data.php?q=relevéEtudiant&semestre=SEM8871

Entrée

semestre : identifiant Scodoc du semestre // Ce paramètre n'est utilisable que si l'utilisateur est reconnu comme "personnel".
[Optionnel] etudiant : identifiant de l'étudiant (adresse mail) sinon, l'adresse de session est automatiquement utilisé.

Sortie

JSON avec les données.

API : Données de première connexion

Cette requête est une combinaison de l'authentification, la liste étudiant, la liste des semestre et du relevé de notes.

Elle permet d'avoir toutes les données en une seule requête pour plus de performances. De plus, le nombre de requêtes à Scodoc est limité grâce à une réutilisation en interne des données.

Query

dataPremièreConnexion

Exemples

https://notes.iutmulhouse.uha.fr/services/data.php?q=dataPremièreConnexion

Entrée

Pas de paramètre d'entrée.

Sortie

// Si personne identifié comme "personnel"
[
	"auth": Données d'authentification,
	"etudiants": Liste des étudiants
]
ou 
// Si personne identifié comme "etudiant"
[
	"auth": Données d'authentification (voir API : Authentification aux services),
	"semestres": Liste des semestres (voir API : Liste des semestres d'un étudiant),
	"relevé": JSON du relevé du dernier semestre suivi par l'étudiant
]

API : Semestres actifs département

Liste des semestres actif d'un département.

Réservé aux utilisateurs avec un statut de "personnel".

Query

semestresDépartement

Exemples

https://notes.iutmulhouse.uha.fr/services/data.php?q=semestresDépartement&dep=MMI

Entrée

dep: département

Sortie

[
	{
		"titre": "titre du semestre",
		"semestre_id": "code semestre" // exemple : 'SEM8871'
	},
	etc.
]

API : Etudiants d'un département

Liste les étudiants d'un département par semestre et groupes.

Réservé aux utilisateurs avec un statut de "personnel".

Query

listesEtudiantsDépartement

Exemples

https://notes.iutmulhouse.uha.fr/services/data.php?q=listesEtudiantsDépartement&dep=MMI

Entrée

dep: département

Sortie

[
	{
		"titre": "Nom du semestre",
		"semestre_id": "SEM8732",
		"groupes": ["groupe 1", "groupe 2", etc.], // Exemple : TP11, TP12, etc.
		"etudiants": [
			{
				"nom": "nom de l'étudiant",
				"prenom": "prenom de l'étudiant",
				"groupe": "groupe 1",
				"num_etudiant" => "numero de l'étudiant",
				"email" => "email UHA de l'étudiant"
			},
			etc.
		]
	},
	etc. avec les autres semestres d'un département, exemple : 1er année, 2ième année, LP, ...
]