API REST [ADEL ]

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
====== API REST ======


===== Introduction =====

Adel met à disposition depuis 2021 ce qu'on appelle une "API REST". De manière résumée, une API est une solution informatique qui permet à des applications de communiquer entre elles, de s'échanger des informations.

Une API met à disposition un ensemble de fonctions qui facilitent l'accès aux services fournis par une application. L'échange d'informations s'effectue à travers un langage de programmation.

Le terme "[[https://fr.wikipedia.org/wiki/Representational_state_transfer|REST]]" désigne le style d'architecture de l'API. Nous ne la détaillerons pas ici.


===== A qui s'adresse ce document ? =====

L'utilisation d'une API REST nécessite des connaissances en programmation informatique. La documentation qui suit s'adresse donc à un profil de développeur. Il y sera question du protocole HTTP, d'authentification JWT, et des exemples de programme seront donnés en langage Javascript.

===== Notes de version =====

  * Dernière mise à jour de ce document : **le 9 septembre 2021**
    * Clarification de la forme de l'URL attendue au niveau de l'implémentation
  * Version d'Adel utilisé lors des tests : **6.4.6** 
  * Version de l'API : **v1**

**Versioning d'API** :\\
Les différentes "routes" de l'API sont préfixées par le numéro de version de l'API.\\ [[https://blog.octo.com/versioning-de-services-rest|En savoir plus]]


===== Documentation OpenAPI =====

L'accès à la documentation technique de l'annuaire ADEL est le suivant :\\
**<nowiki>https://secure.bayard-service.com/annuaire_<MON_ANNUAIRE>/swagger-ui/index.html</nowiki>**

Cette documentation repose sur le standard [[https://www.openapis.org|OpenAPI]] et met à disposition une interface permettant de découvrir les possibilités de l'API mais aussi de **tester les différents services** offerts par celle-ci.

L'interface présente la liste des services de l'API, répartis en 3 sections : 
  * Les groupes
  * Les personnes
  * Les fonctions

Nous vous laissons le soin le découvrir par vous-même la liste de ces services. Vous verrez que certains paramètres d'entrée attendent des valeurs particulières. Celles-ci sont décrites sur cette page dédiée : [[adel:utilisateurs:api-rest:endpoints|Informations complémentaires]].


==== Authentification ====

Les requêtes effectuées sur l'API nécessitent une authentification afin que l'API soit en mesure d'accéder aux données de votre base Adel. C'est pourquoi l'interface de la documentation technique en ligne affiche un bouton "//Authorize//" avec un cadenas ouvert qui précise que vous n'êtes pas encore authentifié.

Pour pouvoir tester les différentes "routes", il est donc nécessaire de l'être. Pour cela, cliquez sur le bouton pour renseigner les informations d'identification.
  * ''username'' et ''password'' : correspondent à un compte d'accès Adel. Ce compte doit être habilité à utiliser l'API.
  * ''client-id'' et ''client-secret'' : Mécanisme complémentaire d'authentification. Les informations à saisir sont à demander à Bayard-Service.

Ces 4 champs étant renseignés, cliquez sur le bouton "Authorize" au bas du formulaire. Le résultat de l'opération s'affiche. Fermez cette petite fenêtre. Le cadenas est alors fermé ce qui indique que l'authentification a réussi. Vous êtes désormais en mesure de tester les différentes "routes".

Le mécanisme d'authentification est expliqué plus en détail dans la partie [[adel:utilisateurs:api-rest:implementation|Implémentation]].