Différences

Ci-dessous, les différences entre deux révisions de la page.

--- adel:utilisateurs:api-rest [2021/02/16 09:55] – ↷ Page déplacée de adel:documentation-interne:api-rest à adel:utilisateurs:api-rest julien.lanfrey
+++ adel:utilisateurs:api-rest [2022/06/13 14:48] (Version actuelle) – eric
@@ Ligne 2: / Ligne 2: @@
-{{:adel:work-in-progress.png?50|}} **ECRITURE EN COURS**
+===== 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.
-===== Introduction =====
+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.
-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 le présent document ? =====
+===== 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 =====
-===== Présentation =====
+  * 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**
-==== Documentation OpenAPI ====
+**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]]
-La documentation technique de l'API est disponible en ligne à l'adresse suivante :\\
-[[https://www.bayard-service.com|Documentation technique de l'API]]
+===== 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.
@@ Ligne 32: / Ligne 38: @@
   * Les fonctions
-Nous vous laissons le soin de découvrir par vous-même la liste de ces services.
+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]].
@@ Ligne 40: / Ligne 45: @@
 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 d'être authentifié. Pour cela, cliquez sur le bouton pour renseigner les informations d'identification.
+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.
+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 sera expliqué plus en détail dans la partie "Implémentation".
-==== Versioning ====
-Les différentes routes de l'API sont préfixés par le numéro de version de l'API. [[https://blog.octo.com/versioning-de-services-rest|En savoir plus sur le concept de versioning d'API]]
-==== Projections ====
-Au niveau des paramètres d'entrée, figure la plupart du temps, un paramètre facultatif nommé "projection". Ce paramètre permet de préciser ce que l'on souhaite obtenir en réponse.
-Si vous testez les différentes routes, vous remarquerez que les informations qu'elles retournent sont toujours minimalistes. Si vous saisissez "huge" comme valeur, vous pourrez voir que les données obtenus sont plus complètes avec notamment les coordonnées, les descriptions publiques, privées, les mots-clés, etc.
-Vous pouvez ainsi moduler vos appels à l'API en précisant "huge" au niveau de la projection selon que vous avez besoin d'informations complètes ou pas. Les requêtes effectuées avec la projection "huge" sont donc plus lourdes et peuvent prendre plus de temps. Cet aspect est à prendre en compte selon l'usage que vous faites de l'API.
-==== Recherche de groupes ====
-Il est possible d'effectuer une recherche de groupes par type, et plus précisément selon ces 3 critères :
-  * typePrincipal
-  * type
-  * sousType
-Ils permettent la réalisation de recherches plus au moins larges, par exemple :
-  * La recherche de tous les établissements, quels qu'ils soient
-  * La recherche des établissements scolaires
-  * La recherche des établissements scolaires de type "collège"
-Les valeurs autorisées pour ces 3 champs sont soit des constantes, soit des libellés qui ont été déclarés sur Adel (dans //Gestion > Administration des données > Type de ...//).
-Voici une arborescence indiquant toutes les combinaisons possibles, avec ''typePrincipal'' au niveau 1, ''type'' au niveau 2, ''sousType'' au niveau 3.
-  * ''**ZONE_GEOGRAPHIQUE**''
-    * ''ZONE_GEOGRAPHIQUE''
-      * Libellé du sous-type déclaré sur Adel
-    * ''DIOCESE''
-      * Libellé de la typologie déclarée sur Adel
-  * ''**ETABLISSEMENT**''
-    * ''ETABLISSEMENT_SCOLAIRE''
-      * Libellé du sous-type déclaré sur Adel
-    * ''ETABLISSEMENT_AUTRE''
-      * Libellé du sous-type déclaré sur Adel
-    * ''LIEU_DE_CULTE''
-      * Libellé du sous-type déclaré sur Adel
-  * ''**ORGANISATION**''
-    * ''COMMUNAUTE''
-    * ''ASSOCIATION''
-    * ''CONGREGATION''
-    * ''MOUVEMENT''
-    * ''ORGANISATION_AUTRE''
-      * Libellé du sous-type déclaré sur Adel
-  * ''**SERVICE**''
-    * ''SERVICE''
-      * Libellé du sous-type déclaré sur Adel
-===== Implémentation =====
-Il est possible d'utiliser à peu près n'importe quel langage de programmation pour utiliser l'API. Nous donnerons quelques exemples en langage Javascript avec la librairie JQuery.
-Les communications avec l'API passent par des requêtes HTTPS GET. Le format d'échange utilisé est le format JSON.
-==== Authentification ====
-Deux standards sont employés dans le but de sécuriser l'API :
-  * HTTP Basic Authentication
-  * OAuth 2.0 JWT, avec échange de Token
-Le principe général est le suivant :
-  - On commence par transmettre des informations d'authentification initiale à l'API (login et mot de passe). L'API vérifie les droits de la personne à utiliser l'API et, le cas échéant lui retourne un ''access_token'' et un ''refresh_token''.
-  - Le ''access_token'' est un identifiant unique qui sert de laisser-passer pour tout appel successif à l'API. Il a une durée de vie relativement courte (de l'ordre de l'heure). Au delà, un nouvel appel à l'API provoquera une erreur.
-  - Le ''refresh_token'' sert à demander à l'API un nouvel ''access_token'', typiquement quand ce dernier a expiré. Il a donc une durée de vie beaucoup plus longue.
-Remarques :
-  * Les appels à l'API sont "stateless" ou "sans état". Cela signifie que l'API ne conserve aucune information en session. C'est le ''access_token'' qui sert de justificatif à chaque appel. Vous devez donc le conserver en mémoire, par exemple dans le "local storage" de votre navigateur s'il s'agit d'une application web.
-  * Il n'existe donc pas de mécanisme (de route) pour se déconnecter. Au niveau de votre application, se "déconnecter" consiste donc à supprimer le ''access_token''. Sans ce dernier, l'utilisateur devra repasser par la phase initiale d'authentification.
-==== Exemples avec la librairie JQuery ====
-=== 1 - Authentification initiale ===
-<code javascript | Authentification : /oauth/token>
-$.ajax({
-    method: 'POST',
-    url: 'https://votre/instance/adel/oauth/token',
-    contentType: 'application/x-www-form-urlencoded; charset=utf-8',
-    crossDomain:true,
-    dataType: 'json',
-    data: {
-        grant_type: 'password',
-        username: 'xxxxx',      // Login Adel
-        password: 'xxxxx',      // Mot de passe Adel
-        client_id: 'xxxxx',     // Basic-auth : id
-        client_secret: 'xxxxx'  // Basic-auth : mot de passe
-    },
-    success: function (data) {
-        console.log('success', data);
-    },
-    error: function (e) {
-        console.log('error', e.responseText);
-    }
-});
-</code>
-Si l'authentification réussie, vous obtiendrez un retour de la forme :
-<code json | Réponse>
-{
- "access_token": "azertyiJIhyhyNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiand0cmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJqbGFuZnJleSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInRydXN0Il0sImV4cCI6MTYxMjU0NDA1MSwiYXV0aG9yaXRpZXMiOlsic3lzX2dsb2JhbF9hZG1pbmlzdHJlciIsIlJPTEVfc3lzX2FkbWluIl0sImp0aSI6IjJiV1lwdEazertyXJ4Nm1hSSIsImNsaWVudF9pZCI6Imp3dGNsaWVudGlkIn0.x6gJRCbsOVVkpnsYduVL9QldGK0qPgW-Hql8mjcqBiQ",
- "token_type": "bearer",
- "refresh_token": "azertyzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiand0cmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJqbGFuZnJleSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInRydXN0Il0sImF0aSI6IjJiV1lwdEQ0QkdaSXJqaFplYTlpTXJ4Nm1hSSIsImF1dGhvcml0aWVzIjpbInN5c19nbG9iYWxfYWRtaW5pc3RyZXIiLCJST0xFX3N5c19hZG1pbiJdLCJqdGkiOiJvd1RkamQwZ3dUTU51MTg3ckNPRlRxT0ZwWHMiLCJjbGllbnRfaWQiOiJqd3RjbGllbnRpZCJ9.hT4WZ5yjloX5zH0Ko6c7WaTWD-ImGQYlmFxsInHVQqU",
- "expires_in": 3559,
- "scope": "read write trust",
- "jti": "azertyD4BGZIrjhZea9iMrx6maI"
-}
-</code>
-=== 2 - Utilisation de l'API ===
-Vous êtes désormais en mesure d'appeler les différentes routes de l'API en transmettant le ''access_token'' à chaque appel.
+Le mécanisme d'authentification est expliqué plus en détail dans la partie [[adel:utilisateurs:api-rest:implementation|Implémentation]].
-<code javascript | Appel de /api/v1/personnes/123>
-$.ajax({
-    method: 'GET',
-    url: 'https://votre/instance/adel/api/v1/personnes/123',
-    dataType: 'json',
-    crossDomain:true,
-    data: {},
-    beforeSend: function (xhr) {
-        xhr.setRequestHeader('Authorization','Bearer ' + store.access_token);
-    },
-    success: function (data) {
-        console.log('success', data);
-    },
-    error: function (e) {
-        console.log('error', e.responseText);
-    }
-});
-</code>
-Si vous utilisez votre ''access_token'' alors que ce dernier a expiré, qu'il n'est plus valide, vous obtiendrez un retour d'erreur de ce type :
-<code json | Utilisation d'un access_token invalide>
-{"error":"invalid_token","error_description":"Access token expired: azertyiJIhyhyNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiand0cmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJqbGFuZnJleSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInRydXN0Il0sImV4cCI6MTYxMjU0NDA1MSwiYXV0aG9yaXRpZXMiOlsic3lzX2dsb2JhbF9hZG1pbmlzdHJlciIsIlJPTEVfc3lzX2FkbWluIl0sImp0aSI6IjJiV1lwdEazertyXJ4Nm1hSSIsImNsaWVudF9pZCI6Imp3dGNsaWVudGlkIn0.x6gJRCbsOVVkpnsYduVL9QldGK0qPgW-Hql8mjcqBiQ"}
-</code>
-=== 3 - Actualisation du ''access_token'' ===
-Si votre ''access_token'' est invalide, vous devez en demander un nouveau en utilisant le ''refresh_token''.
-<code javascript | Actualisation du token : /oauth/token>
-$.ajax({
-    method: 'POST',
-    url: 'https://votre/instance/adel/oauth/token',
-    contentType:'application/x-www-form-urlencoded; charset=utf-8',
-    data: {
-        grant_type: 'refresh_token',
-        refresh_token: store.refresh_token, // Le refresh_token
-        client_id: 'xxxxx',                 // Basic-auth : id
-        client_secret: 'xxxxx'              // Basic-auth : mot de passe
-    },
-    success: function (data) {
-        console.log('success', data);
-    },
-    error: function (e) {
-        console.log('error', e.responseText);
-    }
-});
-</code>
-Le retour est similaire à celui obtenu lors de l'authentification initiale.