From 9987d47ec8c74d649de2a7d09ef62beb885949d9 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 27 Jan 2019 21:47:39 +0100 Subject: Documentation: ajout d’une doc sur l’API REST Signed-off-by: Alban Gruin --- Documentation/usage/rest.rst | 697 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 697 insertions(+) create mode 100644 Documentation/usage/rest.rst (limited to 'Documentation/usage/rest.rst') diff --git a/Documentation/usage/rest.rst b/Documentation/usage/rest.rst new file mode 100644 index 0000000..bcaada9 --- /dev/null +++ b/Documentation/usage/rest.rst @@ -0,0 +1,697 @@ +======== +API REST +======== + +celcatsanitizer dispose d’une API REST pour permettre à des outils +tiers d’accéder facilement à ses données, qui sont renvoyées en JSON. +Pour l’instant, il ne permet pas la modification des données. + +Le point d’entrée se trouve à l’adresse ``api/`` de l’instance de +celcatsanitizer. Il retourne la liste des autres points d’accès en +JSON. + +Années +====== + +``api/years/`` +-------------- +Liste les années par ordre alphabétique de nom. :ref:`Le résultat +peut être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 4, + "next": null, + "previous": null, + "results": [ + { + "id": 3, + "name": "L1", + "slug": "l1" + }, + { + "id": 4, + "name": "L2", + "slug": "l2" + }, + { + "id": 1, + "name": "L3", + "slug": "l3" + }, + { + "id": 2, + "name": "M1", + "slug": "m1" + } + ] + } + +``api/years//`` +------------------- +Retourne seulement une année. + +Exemple : +````````` +.. code:: json + + { + "id": 1, + "name": "L3", + "slug": "l3" + } + +``api/years//timetables`` +----------------------------- +Liste les emplois du temps associés à une année par ordre alphabétique +de nom. :ref:`Le résultat peut être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 2, + "name": "1ere année SRI", + "slug": "1ere-annee-sri", + "year": 1, + "source": 2 + }, + { + "id": 1, + "name": "Info", + "slug": "info", + "year": 1, + "source": 1 + } + ] + } + +Emplois du temps +================ + +``api/timetables`` +------------------ +Liste les emplois du temps par ordre d’année (ID associé) puis de nom. +:ref:`Le résultat peut être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": 1, + "name": "Info", + "slug": "info", + "year": 1, + "source": 1 + } + ] + } + +``api/timetables//`` +------------------------ +Retourne seulement un emploi du temps. + +Exemple : +````````` +.. code:: json + + { + "id": 1, + "name": "Info", + "slug": "info", + "year": 1, + "source": 1 + } + +``api/timetables//groups/`` +------------------------------- +Retourne la liste des groupes associés à un emploi du temps, triés par +ordre alphabétique. :ref:`Le résultat peut être paginé +`. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + }, + { + "id": 208, + "name": "L3 INFO (toutes sections et semestres confondus)", + "celcat_name": "L3 INFO (toutes sections et semestres confondus)", + "mention": "L3 INFO", + "semester": null, + "subgroup": "", + "slug": "l3-info-toutes-sections-et-semestres-confondus", + "hidden": false, + "source": 1 + } + ] + } + +Sources +======= + +``api/sources/`` +---------------- +Retourne la liste des sources par ordre d’ID. :ref:`Le résultat peut +être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 1, + "url": "https://edt.univ-tlse3.fr/calendar/default.aspx?View=month&Type=group&ResourceN ame=formation_ELINFE", + "last_update_date": null + }, + { + "id": 2, + "url": "https://edt.univ-tlse3.fr/calendar/default.aspx?View=month&Type=group&ResourceN ame=formation_ELUSR1_s1", + "last_update_date": null + } + ] + } + +``api/sources//`` +--------------------- +Renvoie seulement une source. + +Exemple : +````````` +.. code:: json + + { + "id": 1, + "url": "https://edt.univ-tlse3.fr/calendar/default.aspx?View=month&Type=group&ResourceName=formation_ELINFE", + "last_update_date": null + } + +``api/sources//timetables/`` +-------------------------------- +Renvoie la liste des emplois du temps associé à une source triés par +ordre alphabétique. :ref:`Le résultat peut être paginé +`. + +Exemple : +````````` +.. code:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": 1, + "name": "Info", + "slug": "info", + "year": 1, + "source": 1 + } + ] + } + +Groupes +======= + +``api/groups/`` +--------------- +Liste les groupes par ordre alphabétique. :ref:`Le résultat peut être +paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + }, + { + "id": 208, + "name": "L3 INFO (toutes sections et semestres confondus)", + "celcat_name": "L3 INFO (toutes sections et semestres confondus)", + "mention": "L3 INFO", + "semester": null, + "subgroup": "", + "slug": "l3-info-toutes-sections-et-semestres-confondus", + "hidden": false, + "source": 1 + } + ] + } + +``api/groups//`` +-------------------- +Affiche seulement un groupe. + +Exemple : +````````` +.. code:: json + + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + } + +.. _ref-groups-courses: + +``api/groups//courses/`` +---------------------------- +Retourne tous les cours d’un groupe et de ses parents triés par ordre +de début. :ref:`Le résultat peut être paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 34723, + "groups": [ + { + "id": 98, + "name": "L3 INFO s1 CMA", + "celcat_name": "L3 INFO s1 CMA", + "mention": "L3 INFO", + "semester": 1, + "subgroup": "A", + "slug": "l3-info-s1-cma", + "hidden": false, + "source": 1 + }, + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + } + ], + "rooms": [], + "name": "REUNION / RENCONTRE", + "type": null, + "notes": "Nuit de l'info", + "begin": "2018-12-06T13:30:00+01:00", + "end": "2018-12-06T23:45:00+01:00", + "last_update": "2018-12-31T13:26:57.122490+01:00", + "source": 1 + }, + { + "id": 34727, + "groups": [ + { + "id": 98, + "name": "L3 INFO s1 CMA", + "celcat_name": "L3 INFO s1 CMA", + "mention": "L3 INFO", + "semester": 1, + "subgroup": "A", + "slug": "l3-info-s1-cma", + "hidden": false, + "source": 1 + }, + { + "id": 207, + "name": "L2 Info s1 CMA", + "celcat_name": "L2 Info s1 CMA", + "mention": "L2 Info", + "semester": 1, + "subgroup": "A", + "slug": "l2-info-s1-cma", + "hidden": false, + "source": 1 + } + ], + "rooms": [], + "name": "REUNION / RENCONTRE", + "type": null, + "notes": "Nuit de l'info", + "begin": "2018-12-07T07:45:00+01:00", + "end": "2018-12-07T23:45:00+01:00", + "last_update": "2018-12-31T13:26:57.136381+01:00", + "source": 1 + } + ] + } + +``api/groups//courses/weeks/`` +---------------------------------- +Retourne la liste des semaines de cours d’un groupe. + +Exemple : +````````` +.. code:: json + + [ + "2018-12-03T00:00:00+01:00" + ] + +``api/groups//courses/weeks/current/`` +------------------------------------------ +Retourne la liste des cours du groupe et de ses parents pendant la +semaine courante (ou prochaine lors du week-end) d’un groupe, par +ordre de début. :ref:`Le résultat peut être paginé `. +Le format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +.. _ref-groups-courses-week-arg: + +``api/groups//courses/weeks///`` +------------------------------------------------ +Retourne la liste des cours du groupe et de ses parents pendant la +semaine spécifiée, par ordre de début. Si l’année et la semaine ne +sont pas des nombres, un code 404 est renvoyé. Si la semaine n’est +pas comprise entre 1 et 53, une erreur 400 est renvoyée, et les +erreurs rencontrées sont renvoyées. :ref:`Le résultat peut être +paginé `. Le format du résultat est identique à celui +de :ref:`api/groups/\/courses/ `. + +Exemple d’erreur (``api/groups//courses/weeks/2018/111/``) : +```````````````````````````````````````````````````````````````` +.. code:: json + + { + "week": "Rentrez une semaine valide" + } + +Salles +====== + +``api/rooms/`` +-------------- +Liste les salles par ordre alphabétique. :ref:`Le résultat peut être +paginé `. + +Exemple : +````````` +.. code:: json + + { + "count": 3, + "next": null, + "previous": null, + "results": [ + { + "id": 26, + "name": "1R1-010", + "slug": "1r1-010" + }, + { + "id": 11, + "name": "1TP1-B08", + "slug": "1tp1-b08" + }, + { + "id": 5, + "name": "1TP1-B08bis", + "slug": "1tp1-b08bis" + } + ] + } + +``api/rooms/`` +------------------ +Renvoie une seule salle. + +Exemple : +````````` +.. code:: json + + { + "id": 26, + "name": "1R1-010", + "slug": "1r1-010" + } + +``api/rooms//courses/`` +--------------------------- +Renvoie la liste des cours se déroulant dans une salle par ordre de +début. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +``api/rooms//courses/weeks/current/`` +----------------------------------------- +Renvoie la liste des cours se déroulant dans une salle pendant la +semaine courante (ou la semaine prochaine le week-end) par ordre de +début. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +``api/rooms//courses/weeks///`` +----------------------------------------------- +Renvoie la liste des cours se déroulant dans une salle pendant la +semaine spécifiée. Si l’année et la semaine ne sont pas des nombres, +un code 404 est renvoyé. Si la semaine n’est pas comprise entre 1 et +53, une erreur 400 est renvoyée, et les erreurs rencontrées sont +renvoyées. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/weeks/\/\ +`. + +``api/rooms/qsjps////`` +---------------------------------------- +Fournit un accès à QSJPS. ```` est une date devant être formatée +de cette manière : ``YYYY-MM-DD``. ```` et ```` sont des +heures qui doivent être formatées de cette manière : ``HH:mm``. La +valeur de ```` doit être inférieure à celle de ````. + +Renvoie la liste des salles vides le début du jour ```` de +```` à ````. + +En cas de mauvais formatage, une erreur 400 est renvoyée, et les +erreurs sont détaillées dans le corps de la réponse. Sinon, la liste +des salles libres est renvoyée. + +Exemple : +````````` +.. code:: json + + [ + { + "id": 26, + "name": "1R1-010", + "slug": "1r1-010" + }, + { + "id": 11, + "name": "1TP1-B08", + "slug": "1tp1-b08" + }, + { + "id": 5, + "name": "1TP1-B08bis", + "slug": "1tp1-b08bis" + } + ] + +Exemple d’erreur (``api/rooms/qsjps/2019-01-35/12:00/10:00/``) : +```````````````````````````````````````````````````````````````` +.. code:: json + + { + "day": [ + "Saisissez une date valide." + ], + "end": [ + "L’heure de début doit être supérieure à celle de fin." + ] + } + +Exemple d’erreur (``api/rooms/qsjps/2019-01-35/12:70/10:70/``) : +```````````````````````````````````````````````````````````````` +.. code:: json + + { + "day": [ + "Saisissez une date valide." + ], + "begin": [ + "Saisissez une heure valide." + ], + "end": [ + "Saisissez une heure valide." + ] + } + +Cours +===== + +``api/courses/`` +---------------- +Renvoie la liste des cours. :ref:`Le résultat peut être paginé +`. + +Exemple : +````````` +.. code:: json + + { + "count": 4766, + "next": "http://localhost:8000/api/courses/?page=2", + "previous": null, + "results": [ + { + "id": 22133, + "groups": [ + { + "id": 98, + "name": "L3 INFO s1 CMA", + "celcat_name": "L3 INFO s1 CMA", + "mention": "L3 INFO", + "semester": 1, + "subgroup": "A", + "slug": "l3-info-s1-cma", + "hidden": false, + "source": 1 + } + ], + "rooms": [ + { + "id": 1, + "name": "Amphi AMPERE (3A)", + "slug": "amphi-ampere-3a" + } + ], + "name": "REUNION / RENCONTRE", + "type": null, + "notes": null, + "begin": "2018-09-04T15:45:00+02:00", + "end": "2018-09-04T16:45:00+02:00", + "last_update": "2018-09-26T19:34:12.924533+02:00", + "source": 1 + }, + … + ] + } + +``api/courses/`` +-------------------- +Renvoie un seul cours. + +Exemple : +````````` +.. code:: json + + { + "id": 22133, + "groups": [ + { + "id": 98, + "name": "L3 INFO s1 CMA", + "celcat_name": "L3 INFO s1 CMA", + "mention": "L3 INFO", + "semester": 1, + "subgroup": "A", + "slug": "l3-info-s1-cma", + "hidden": false, + "source": 1 + } + ], + "rooms": [ + { + "id": 1, + "name": "Amphi AMPERE (3A)", + "slug": "amphi-ampere-3a" + } + ], + "name": "REUNION / RENCONTRE", + "type": null, + "notes": null, + "begin": "2018-09-04T15:45:00+02:00", + "end": "2018-09-04T16:45:00+02:00", + "last_update": "2018-09-26T19:34:12.924533+02:00", + "source": 1 + } + +.. _ref-pagination: + +Pagination +========== +Il est possible que les résultats soient paginés. Cela dépend de la +configuration de l’instance de celcatsanitizer. Dans ce cas, tous les +appels à des points d’accès renvoyant des résultats pouvant être +paginés se trouvent dans ce genre de structure : + +.. code:: json + + { + "count": 4766, + "next": "http://localhost:8000/api/courses/?page=2", + "previous": null, + "results": [ + … + ] + } + + - ``count`` représente le nombre d’éléments au total (et non pas sur + la page). + - ``next`` est le lien de la page de résultats suivants, si il y en a + une. + - ``previous`` est le lien de la page de résultats précédents, si il + y en a une. + - ``results`` est la liste des résultats, si il y en a. -- cgit v1.2.1 From 61eb694cd445fd5f17c4dc6ded0b1d1f5eccdf57 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Tue, 5 Feb 2019 18:00:59 +0100 Subject: Documentation: correction de la doc de l’API Signed-off-by: Alban Gruin --- Documentation/usage/rest.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'Documentation/usage/rest.rst') diff --git a/Documentation/usage/rest.rst b/Documentation/usage/rest.rst index bcaada9..60c8d44 100644 --- a/Documentation/usage/rest.rst +++ b/Documentation/usage/rest.rst @@ -98,8 +98,8 @@ Exemple : Emplois du temps ================ -``api/timetables`` ------------------- +``api/timetables/`` +------------------- Liste les emplois du temps par ordre d’année (ID associé) puis de nom. :ref:`Le résultat peut être paginé `. @@ -688,10 +688,10 @@ paginés se trouvent dans ce genre de structure : ] } - - ``count`` représente le nombre d’éléments au total (et non pas sur - la page). - - ``next`` est le lien de la page de résultats suivants, si il y en a - une. - - ``previous`` est le lien de la page de résultats précédents, si il - y en a une. - - ``results`` est la liste des résultats, si il y en a. +- ``count`` représente le nombre d’éléments au total (et non pas sur + la page). +- ``next`` est le lien de la page de résultats suivants, si il y en a + une. +- ``previous`` est le lien de la page de résultats précédents, si il + y en a une. +- ``results`` est la liste des résultats, si il y en a. -- cgit v1.2.1 From 09a5b8cb97769853ac8a3982bcb340c4c1422498 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Tue, 5 Feb 2019 19:14:48 +0100 Subject: Documentation: ajout des nouvelles routes dans la doc et corrections Signed-off-by: Alban Gruin --- Documentation/usage/rest.rst | 71 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 62 insertions(+), 9 deletions(-) (limited to 'Documentation/usage/rest.rst') diff --git a/Documentation/usage/rest.rst b/Documentation/usage/rest.rst index 60c8d44..4908d8a 100644 --- a/Documentation/usage/rest.rst +++ b/Documentation/usage/rest.rst @@ -64,8 +64,8 @@ Exemple : "slug": "l3" } -``api/years//timetables`` ------------------------------ +``api/years//timetables/`` +------------------------------ Liste les emplois du temps associés à une année par ordre alphabétique de nom. :ref:`Le résultat peut être paginé `. @@ -398,6 +398,41 @@ Exemple : ] } +``api/groups//courses/days/current/`` +----------------------------------------- +Retourne la liste des cours du groupe et de ses parents d’un groupe +pendant le jour courant, par ordre de début. :ref:`Le résultat peut +être paginé `. Le format du résultat est identique à +celui de :ref:`api/groups/\/courses/ `. + +.. _ref-groups-courses-day-arg: + +``api/groups//courses/days////`` +------------------------------------------------------ +Retourne la liste des cours du groupe et de ses parents pendant le +jour spécifié, par ordre de début. Si l’année, le mois ou le jour ne +sont pas des nombres, un code 404 est renvoyé. Si la date est +invalide, une erreur 400 est renvoyée, et les erreurs rencontrées sont +renvoyées. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +Exemple d’erreur (``api/groups//courses/days/2018/111/22``) : +````````````````````````````````````````````````````````````````` +.. code:: json + + { + "month": "Rentrez un mois valide" + } + +Exemple d’erreur (``api/groups//courses/days/2018/11/33``) : +```````````````````````````````````````````````````````````````` +.. code:: json + + { + "day": "Numéro de jour invalide pour le mois" + } + ``api/groups//courses/weeks/`` ---------------------------------- Retourne la liste des semaines de cours d’un groupe. @@ -423,7 +458,7 @@ Le format du résultat est identique à celui de ``api/groups//courses/weeks///`` ------------------------------------------------ Retourne la liste des cours du groupe et de ses parents pendant la -semaine spécifiée, par ordre de début. Si l’année et la semaine ne +semaine spécifiée, par ordre de début. Si l’année ou la semaine ne sont pas des nombres, un code 404 est renvoyé. Si la semaine n’est pas comprise entre 1 et 53, une erreur 400 est renvoyée, et les erreurs rencontrées sont renvoyées. :ref:`Le résultat peut être @@ -473,8 +508,8 @@ Exemple : ] } -``api/rooms/`` ------------------- +``api/rooms//`` +------------------- Renvoie une seule salle. Exemple : @@ -494,6 +529,24 @@ début. :ref:`Le résultat peut être paginé `. Le format du résultat est identique à celui de :ref:`api/groups/\/courses/ `. +``api/rooms//courses/days/current/`` +---------------------------------------- +Retourne la liste des cours se déroulant dans une salle pendant le +jour courant, par ordre de début. :ref:`Le résultat peut être paginé +`. Le format du résultat est identique à celui de +:ref:`api/groups/\/courses/ `. + +``api/rooms//courses/days////`` +----------------------------------------------------- +Retourne la liste des cours se déroulant dans une salle pendant le +jour spécifié, par ordre de début. Si l’année, le mois ou le jour ne +sont pas des nombres, un code 404 est renvoyé. Si la date est +invalide, une erreur 400 est renvoyée, et les erreurs rencontrées sont +renvoyées. :ref:`Le résultat peut être paginé `. Le +format du résultat est identique à celui de +:ref:`api/groups/\/courses/days/\/\/\/ +`. + ``api/rooms//courses/weeks/current/`` ----------------------------------------- Renvoie la liste des cours se déroulant dans une salle pendant la @@ -505,12 +558,12 @@ format du résultat est identique à celui de ``api/rooms//courses/weeks///`` ----------------------------------------------- Renvoie la liste des cours se déroulant dans une salle pendant la -semaine spécifiée. Si l’année et la semaine ne sont pas des nombres, +semaine spécifiée. Si l’année ou la semaine ne sont pas des nombres, un code 404 est renvoyé. Si la semaine n’est pas comprise entre 1 et 53, une erreur 400 est renvoyée, et les erreurs rencontrées sont renvoyées. :ref:`Le résultat peut être paginé `. Le format du résultat est identique à celui de -:ref:`api/groups/\/courses/weeks/\/\ +:ref:`api/groups/\/courses/weeks/\/\/ `. ``api/rooms/qsjps////`` @@ -629,8 +682,8 @@ Exemple : ] } -``api/courses/`` --------------------- +``api/courses//`` +--------------------- Renvoie un seul cours. Exemple : -- cgit v1.2.1 From c2a2f5aac817d4255c30c447808ec08faecda036 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 9 Jun 2019 19:41:38 +0200 Subject: api: ajout d’un paramètre pour activer ou non l’API L’API devient optionnelle, et un paramètre, CS_ENABLE_API, est rajouté pour sélectionner son état (activé ou non). Par défaut, il est désactivé. La documentation est mise à jour pour refléter ces changements. Signed-off-by: Alban Gruin --- Documentation/usage/rest.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation/usage/rest.rst') diff --git a/Documentation/usage/rest.rst b/Documentation/usage/rest.rst index 4908d8a..d18eaa5 100644 --- a/Documentation/usage/rest.rst +++ b/Documentation/usage/rest.rst @@ -10,6 +10,9 @@ Le point d’entrée se trouve à l’adresse ``api/`` de l’instance de celcatsanitizer. Il retourne la liste des autres points d’accès en JSON. +En fonction de la configuration de celcatsanitizer, l’API ne sera +peut-être pas disponible. + Années ====== -- cgit v1.2.1