========
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é <ref-pagination>`.

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/<id>/``
-------------------
Retourne seulement une année.

Exemple :
`````````
.. code:: json

  {
      "id": 1,
      "name": "L3",
      "slug": "l3"
  }

``api/years/<id>/timetables``
-----------------------------
Liste les emplois du temps associés à une année par ordre alphabétique
de nom.  :ref:`Le résultat peut être paginé <ref-pagination>`.

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é <ref-pagination>`.

Exemple :
`````````
.. code:: json

  {
      "count": 1,
      "next": null,
      "previous": null,
      "results": [
          {
              "id": 1,
              "name": "Info",
              "slug": "info",
              "year": 1,
              "source": 1
          }
      ]
  }

``api/timetables/<id>/``
------------------------
Retourne seulement un emploi du temps.

Exemple :
`````````
.. code:: json

  {
    "id": 1,
    "name": "Info",
    "slug": "info",
    "year": 1,
    "source": 1
  }

``api/timetables/<id>/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é
<ref-pagination>`.

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é <ref-pagination>`.

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/<id>/``
---------------------
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/<id>/timetables/``
--------------------------------
Renvoie la liste des emplois du temps associé à une source triés par
ordre alphabétique.  :ref:`Le résultat peut être paginé
<ref-pagination>`.

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é <ref-pagination>`.

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/<id>/``
--------------------
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/<id>/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é <ref-pagination>`.

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/<id>/courses/weeks/``
----------------------------------
Retourne la liste des semaines de cours d’un groupe.

Exemple :
`````````
.. code:: json

  [
      "2018-12-03T00:00:00+01:00"
  ]

``api/groups/<id>/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é <ref-pagination>`.
Le format du résultat est identique à celui de
:ref:`api/groups/\<id>/courses/ <ref-groups-courses>`.

.. _ref-groups-courses-week-arg:

``api/groups/<id>/courses/weeks/<year>/<week>/``
------------------------------------------------
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é <ref-pagination>`.  Le format du résultat est identique à celui
de :ref:`api/groups/\<id>/courses/ <ref-groups-courses>`.

Exemple d’erreur (``api/groups/<id>/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é <ref-pagination>`.

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/<id>``
------------------
Renvoie une seule salle.

Exemple :
`````````
.. code:: json

  {
      "id": 26,
      "name": "1R1-010",
      "slug": "1r1-010"
  }

``api/rooms/<id>/courses/``
---------------------------
Renvoie la liste des cours se déroulant dans une salle par ordre de
début.  :ref:`Le résultat peut être paginé <ref-pagination>`.  Le
format du résultat est identique à celui de
:ref:`api/groups/\<id>/courses/ <ref-groups-courses>`.

``api/rooms/<id>/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é <ref-pagination>`.  Le
format du résultat est identique à celui de
:ref:`api/groups/\<id>/courses/ <ref-groups-courses>`.

``api/rooms/<id>/courses/weeks/<year>/<week>/``
-----------------------------------------------
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é <ref-pagination>`.  Le
format du résultat est identique à celui de
:ref:`api/groups/\<id>/courses/weeks/\<year>/\<week>
<ref-groups-courses-week-arg>`.

``api/rooms/qsjps/<day>/<begin>/<end>/``
----------------------------------------
Fournit un accès à QSJPS.  ``<day>`` est une date devant être formatée
de cette manière : ``YYYY-MM-DD``.  ``<begin>`` et ``<end>`` sont des
heures qui doivent être formatées de cette manière : ``HH:mm``.  La
valeur de ``<begin>`` doit être inférieure à celle de ``<end>``.

Renvoie la liste des salles vides le début du jour ``<day>`` de
``<begin>`` à ``<end>``.

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é
<ref-pagination>`.

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/<id>``
--------------------
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.