API Idéfix

Ce document décrit l'interface de programmation (en anglais, abbrévié API) offerte par le SRAM pour récupérer des fichiers au format Idéfix. Le format de ces documents est lui-même décrit par un schéma XSD.

Cet API permet de demander la production des fichiers ainsi que leur récupération à partir d'un même serveur. L'API se conforme au style d'architecture REST, offrant des ressources à des URLs spécifiques sur un serveur Web et acceptant une série d'actions sur ces ressources. Une familiarité avec ce style d'architecture est recommandé avant la lecture de ce document.

#Hôtes et version

L'interface programmaticale est hébergée au sein du site classer-direct-sram.qc.ca et est disponible à partir de l'URL https://classer-direct-sram.qc.ca/v1. Le préfixe de chemin v1 ici indique la version de l'API qui se retrouve à cette adresse (1). Tout changement important à l'interface programmaticale entrainera une augmentation de ce numéro de version, permettant l'existence concurrente de plusieurs versions.

Les chemins d'URLs contenus dans ce document et servant à décrire les diverses ressources pouvant être manipulées assument toutes appartenir à ce serveur.

Le serveur doit être accédé par HTTPS, et donc par le port 443.

#Format

L'API utilise le format de données JSON encodé selon l'encodage de caractères UTF-8, à l'exception des fichiers Idéfix eux-mêmes qui sont des documents au format XML.

À moins qu'il en soit indiqué autrement, le corps des requêtes POST et PUT doit être un objet JSON. Les requêtes de type POST et DELETE ont plutôt leurs paramètres passés dans la query string. Un array passé dans une query string l'est en créant une chaine dont les éléments sont séparés par des virgules. Par exemple, la chaine AB,CD,EF dans une query string correspond, en JSON à:

["AB", "CD", "EF"]

#Gestion des erreurs

Toutes les méthodes, en plus d’un code de retour HTTP approprié, retournent, lorsque le Content-Type est application/json et qu’une erreur s'est produite un objet JSON décrivant l'erreur:

{
  "code": 1001,
  "message": "Query string invalide"
}

Quand il y a des champs impliqués dans l'erreur, par exemple des paramètres sont invalides, l'objet retourné pourrait inclure un attribut erreurs indiquant quels champs sont en erreur:

{
  "code": 1001,
  "message": "Query string invalide",
  "erreurs": [
    {
      "champ": "session",
      "code": 1002,
      "message": "Cette valeur est requise."
    }, {
      "champ": "tour",
      "code": 1002,
      "message": "Cette valeur doit être un entier entre 1 et 4 ou la chaine 'ls24'."
    }
  ]
}

#Authentification

L'accès aux fonctions du système requiert qu'une clé d'API soit envoyée avec chaque requête au système. Cette clé est rattachée à un utilisateur, soit une personne ou un système, et reçoit un sous-ensemble des permissions de l'utilisateur. Dans ce cas-ci, la permission d'accéder aux fonctions Idéfix du système Classer-Direct. Les collèges auxquels une clé donne accès sont ceux auxquels l'utilisateur a accès. Chaque clé est une séquence de caractères alphanumériques et d'un seul point, par exemple:

3mB7rdca.WXf2Ny86DJL7zVZB7pbT

Pour des raisons de sécurité, la clé est souvent identifiée uniquement par la partie précédent le point. Par contre, la clé entière doit être fournie au système Classer-Direct afin d'avoir accès à ses fonctions.

La clé est passée au système via l'entête HTTP Authorization avec le schème Bearer. La clé ne doit pas être encodée en base64 ou tout autre encodage spécial. Pour la clé mentionnée ci-haut, cela donnerait:

Authorization: Bearer 3mB7rdca.WXf2Ny86DJL7zVZB7pbT

Une clé peut être activée et désactivée par l'utilisateur associé à la clé et n'est plus valide dès que les permissions pour cette utilisateur sont retirés par le SRAM. Il est donc préférable d'utiliser une clé pour chaque utilisateur du programme effectuant l'accès aux fichiers Idéfix, plutôt qu'une clé par application et ce, même si la précédente version du système utilisait un utilisateur SRAM par collège dont le nom et le mot de passe était partagé par tous les utilisateurs effectifs du système. Dans le cas où cela s'avèrerait techniquement impossible, le SRAM permet aussi l'emploi d'un utilisateur par collège. Dans tous les cas, le client travaillant dans un collège devrait être celui qui a accès à la clé d'API, l'entrant à un endroit approprié dans l'application, plutôt que le développeur de l'application. La gestion de la clé d'API se fait par l'entremise du site Voute et sa création initiale requiert une demande d'accès au SRAM.

#Limites de rythme

Pour l'instant, le SRAM n'impose aucune limite explicite sur le nombre de requêtes pouvant être effectuées dans une période donnée. Il se réserve cependant le droit d'imposer une telle limite sans préavis. Dans quel cas, les requêtes retourneraient le code HTTP 429 Too Many Requests.

Afin d'éviter l'imposition de telles limites, cependant, nous vous demandons de vous limiter à au plus une requête par seconde par client (ex.: par cégep ou par poste de travail). De plus, puisque la génération de fichiers peut prendre jusqu'à plusieurs minutes, vous ne devriez pas appeler la ressource pour le contenu d'un fichier moins de 10 secondes après avoir obtenu le code 404 Not Found ou 450 pour cette exacte ressource.

#Principe général

Le système reçoit des requêtes de génération de fichiers Idéfix. Une requête peut ne générer aucun fichier, en générer un seul ou en générer plusieurs. Ces requêtes sont ajoutées au système immédiatement via l'API, mais les fichiers à produire pour une requête donnée sont traités un à la fois par le système. Le programme qui interface via l'API devrait donc minimalement procéder selon les étapes suivantes:

1. Demander l'ajout d'une requête de fichiers Idéfix (POST /v1/idefix);
2. Obtenir le détail de la requête ajoutée (GET /v1/idefix/{id_requete});
3. Pour chaque fichier à générer pour la requête:
   1. Demander le contenu du fichier (GET /v1/idefix/{id_requete}/fichiers/{id_fichier}/contenu);
   2. Si code de la réponse est 200, le corps de la réponse sera le fichier Idéfix produit et le programme peut passer au prochain fichier;
   3. Sinon, attendre au moins 10 secondes;
   4. Répéter la demande de contenu.

Les requêtes et les fichiers périmés n'ont pas besoin d'être explicitement supprimés par l'appelant; ceux-ci sont automatiquement retirés après un certain temps.

#Actions

#Lister les requêtes

Description:

Retourne les requêtes de fichiers Idéfix demandées par l'utilisateur associé à la clé d'API utilisée. Les requêtes peuvent être filtrées par les paramètres ayant été spécifié lors de leur ajout au système.

Paramètres (query string):

Résultat:

Un array d'objets JSON ayant les attributs suivants:

Erreurs:

• 400: Les paramètres sont mal formés.

#Ajouter une requête

Description:

Ajoute une requête de production de fichiers au système. Le système retourne immédiatement la ressource correspondante, mais les fichiers seront produits au fur-et-à-mesure que les ressources seront disponibles pour le faire. Normalement, une requête produira un fichier par collège, session et tour ayant des candidats concernés.

Paramètres (corps):

Si nosDaSession est spécifié, colleges et session deviennent optionnels.

Résultat:

Un objet JSON ayant les attributs suivants:

Erreurs:

• 400: Les paramètres sont mal formés (sous-code 1003) ou le groupe demandé est introuvable (sous-code 1008).
• 403: L'utilisateur n'a pas accès aux collèges demandés (sous-code 1006) ou aux fonctions Idéfix.

#Obtenir le détail d'une requête

Description:

Retourne le détail complet d'une requête de fichiers Idéfix.

Résultat:

Un objet JSON ayant les mêmes attributs que pour l'ajout d'une requête.

Erreurs:

• 404: La requête n'existe pas pour cet utilisateur (sous-code 1005). Elle pourrait avoir existé et avoir été retirée par le système. Elle pourrait également appartenir à un autre utilisateur.

#Lister les fichiers produits par une requête

Description:

Retourne la liste des fichiers qui sont à produire pour la requête donnée.

Résultat:

Un array d'objets JSON ayant les attributs suivants:

Erreurs:

• 404: La requête n'existe pas pour cet utilisateur (sous-code 1005). Elle pourrait avoir existé et avoir été retirée par le système. Elle pourrait également appartenir à un autre utilisateur.

#Obtenir le détail d'un fichier à produire

Description:

Retourne le détail complet d'un fichier à produire.

Résultat:

Un objet JSON ayant les attributs suivants:

Erreurs:

• 404: La requête ou le fichier n'existe pas pour cet utilisateur (sous-code 1005).

#Obtenir le contenu d'un fichier

Description:

Retourne le contenu d'un fichier Idéfix si celui-ci est disponible.

Résultat:

Le contenu du fichier Idéfix. Le contenu n'est pas en JSON, mais est plutôt retourné directement.

Erreurs:

• 404: La requête ou le fichier n'existe pas pour cet utilisateur (sous-code 1005) ou le fichier demandé n'est pas disponible (sous-code 1007).
• 450: Le contenu du fichier demandé n'est pas disponible (sous-code 1007).