Référence

Tous les détails dont vous avez besoins

API

L'api d'Edu-Focus fonctionne selon le principe REST avec le protocole HTTPS. Tous les accès à l'api se font avec la racine:

https://api.edu-focus.org/

L'api dispose de plusieurs versions, par défaut la version utilisée est celle avec un ✔ à coté d'elle. Si vous souhaitez utiliser une autre version que celle par défaut, vous pouvez y accéder via l'url https://api.edu-focus.org/v{version}.

Version

Status

Actuelle

1

Développement en cours

Authentification

Tous les endpoints de l'api requièrent une authentification. Il y a deux manières de s'authentifier auprès de l'api:

  • En utilisant l'authentification basique avec l'id de votre application comme identifiant et le secret comme mot de passe. Détails [EN]

  • En utilisant un token Bearer obtenu via OAuth, pour savoir comment utiliser OAuth, rendez vous sur cette page.

Peu importe la méthode, vous devez passer votre token d'autorisation avec le header Authorization.

Accès direct
Via un token OAuth
Accès direct
Authorization: Basic Q2VjaSBlc3QgZXZpZGVtZW50IHVuIGZhdXggdG9rZW4=
Via un token OAuth
Authorization: Bearer vJejUluQsWnw4BSwrCzARHnFoyCqF7RlXRdWF25N

Sécurité

Toutes les requêtes HTTP doivent utiliser TLS (https). Les requêtes en http auront comme réponses une redirection vers la même url en https avec un code 301.

Identifiants uniques

Les identifiants uniques ou ID servent à identifier toutes les ressources, il suivent tous certains principes:

  • Ils sont toujours composés des 62 mêmes caractères: les 26 lettres de l'alphabet français en minuscule et en majuscule et les 10 chiffres arabes;

  • Ils sont sensibles à la casse (c'est à dire qu'il font la distinction entre les majuscules et les minuscules);

  • Ils sont générés de manière cryptographiquement aléatoire;

  • Ils sont uniques;

Deux ressources différentes peuvent avoir le même identifiant (ex: une application et un utilisateur).

Détails par ressource

Voici quelques informations complémentaires des spécificités des identifiants de chaque ressources.

Ressource

Longueur de l'identifiant

Expression régulière

Utilisateurs

8

^[a-zA-Z0-9]{8}$

Applications

Entre 1 et 32 (généralement 32)

^[a-zA-Z0-9]{1,32}$

Suspensions

8

^[a-zA-Z0-9]{8}$

Interragir avec l'api

L'api fonctionne sous le principe REST (REpresentational State Transfer). Pour voir tous les détails quand à la communication avec l'api et notament les réponses, merci de consulter le sujet Communiquer avec l'API.

Envoi et récéption de fichiers

Pour tous les détails relatifs au fichiers utilisés par les services d'edu-focus, merci de consulter le sujet Fichiers.

Objets de l'api

Sur les pages des différentes api vous sont présentés des objets, ce sont les représentation d'un element de l'api tel qu'il vous sera transmis et tel que vous devrez le transmettre (totalement ou partiellement). Ici vous trouverez les détails de comment lire ces tableaux.

Types

Sur les tableaux vous trouverez une colonne type qui vous indique le type du champ. Ces types sont les types JSON [EN].

Type

Description

string

Une chaine de caractères

int

Un nombre entier naturel (pas de virgules)

float

Un nombre réel (peut potentiellement avoir des virgules)

bool

Un état logique (vrai ou faux).

object

Un objet, généralement fourni avec un référence vers le détail de son contenu

Liste d'éléments

Parfois vous verrez le type écris comme ceci: string[]. Ceci signifie que la valeur est une liste d'éléments du type indiqué (ici une liste de chaines de caractères).

Nullables

D'autres fois vous verrez le type écris comme ceci: ?string. Cela veut dire que la valeur du champs peut être soit null, soit du type indiqué (ici chaine de caractères).

Champs optionnels

Parfois, il peut arriver que le nom certains champs soit préfixé d'un ? cela signifie que le champs est optionnel et qu'il ne sera pas nécéssairement présent sur la réponse. La plupart du temps des indications supplémentaires sont disponibles dans la déscription du champs.

Temps

Parfois il est nécéssaire de communiquer des temps avec l'api, cela ce fait au travers de ce que l'on apelle des timestamps. Les timestamps, késako ? Les timestamps sont des nombres qui représentent le temps écoulé en seconde depuis un point précis: le temps 0.

Seconde 0

Les timestamps que vous evoyez à l'api et ceux que vous recevez d'elle doivent tous avoir le même temps 0:

1 janvier 1970 à 00:00:00