Page 1: Le constructeur de requêtes
La page “API” disponible dans les paramètres du module User, permet à un administrateur de générer facilement l'URL dont il a besoin pour interroger l'API.
Elle est accessible aux administrateurs d’au moins un module.
1.1. Sélection des données (Entités Pyx4 disponibles)
L'utilisateur commence par choisir les entités de données qu'il souhaite extraire (Graphes, Actions, Utilisateurs, etc.) dans le panneau “Contenu de la requête”.
L'utilisateur peut sélectionner autant d’entités qu’il lui reste de crédits disponibles en sachant que 1 entité = 1 crédit.
1.2. Filtres
Le panneau “Paramètres” permet d'appliquer des filtres précis pour restreindre les résultats de l'API.
- Période: L'utilisateur sélectionne une date de début et une date de fin de sorte à ce que les résultats retournés soient compris entre ces 2 dates.
- Propriété de tri : Permet d'ordonner les résultats selon la date de création, la date de mise à jour, ou par ordre alphabétique.
- Ordre : Descendant ou Ascendant.
- Responsabilité dans l’élément : Placer le toggle sur On demandera à l’API de ne retourner que des éléments dans lesquels l’utilisateur a une responsabilité (auteur, contributeur, etc).
- Nombre maximal d'éléments : Permet de limiter le nombre de résultats retournés. Si plusieurs entités sont sélectionnées, alors la limite de résultats retournés sera la même pour chaque entité.
Valeurs par défaut : Si l'utilisateur ne touche à aucun filtre, la requête générée appliquera les filtres suivants :
- Aucune limite de date.
- Tri par date de création, ordre descendant.
- Responsabilité Off.
- Aucune limite de résultats (tous les éléments sont retournés).
1.3. Le système de crédits
L’API fonctionne avec un système de crédits partagés au niveau de l’instance (et non par utilisateur individuel). Les crédits sont réinitialisés chaque jour, dépendamment de la formule choisie par le client.
Chaque entité coûte 1 crédit. Par exemple, si l’utilisateur sélectionne "Graphes" et "Actions", sa requête coûtera 2 crédits et “Crédits requis pour la requête” affichera 2. Les filtres n’ont aucune incidence sur le coût de la requête.
Pour savoir ce qu’il peut faire, l’utilisateur peut voir en tout temps le nombre de crédits restants en haut à droite, dans “Crédits restants”. Ce nombre est mis à jour en temps réel. C’est-à-dire que si quelqu’un d’autre est en train d’utiliser l’API en exécutant une requête, la page sera automatiquement mise à jour en fonction du nombre de crédits qu'a utilisés l’autre personne.
Si le coût de la requête en préparation dépasse le solde de crédits restants de l’instance, les entités et les filtres sélectionnées deviennent désélectionnés
1.4. Génération de la requête
L'URL de la requête se met à jour instantanément à entité sélectionnée ou changement de paramètre.
Un clic sur le bouton "Copier" copie l’URL, prête à être collée dans l'outil du client. Ce dernier pourra ensuite ajouter sa clé d’API (voir ci-dessous) directement dans l’URL à l’endroit dédié en sachant que dans l’URL, YOUR_KEY_VALUE correspond à sa clé d’API.
Page 2 : Les clés API (API Keys)
La page “API Keys” permet de générer, consulter et supprimer les clés de l’API, nécessaires à son utilisation.
Elle n’est accessible qu’aux administrateurs du module User Management.
2.1. Le tableau de bord
La page présente la liste de toutes les clés API actuellement actives sur l'instance, affichées par ordre de dernière utilisation.
2.2. Création d'une nouvelle clé
La création d'une clé répond à certaines règles :
- Seuls les administrateurs d’au moins un module peuvent recevoir une clé.
- Un administrateur ne peut posséder qu'une seule clé active à la fois.
- Une fois le bouton "Créer la clé" cliqué, la clé API est générée et affichée de sorte à pouvoir être copiée. Attention, c'est la seule et unique fois que cette clé sera visible.
- Si l’utilisateur perd sa clé ou oublie de la copier, il ne sera pas possible de la récupérer. La seule solution reste de supprimer l'ancienne clé et d'en recréer une nouvelle.
- Si un administrateur possède une clé et se voit rétrogradé plus tard en tant que simple utilisateur, sa clé sera automatiquement désactivée. De même si son compte est désactivé de l’instance.
2.3. Suppression
L'utilisateur peut supprimer une ou plusieurs clés à la fois en les sélectionnant une par une. Le bouton "Supprimer" apparaît dès qu'une case est cochée.
La suppression d'une clé bloque immédiatement l’utilisation de l’API au détenteur de la clé, et une erreur lui sera retournée. Aucun crédit ne sera décompté en cas d’erreur.
Page 3 : Exemples d’utilisation pour les données PYX4
Voici un exemple pratique d’utilisation de la fonctionnalité dès la génération de votre clé jusqu’à l’automatisation d’un flux pour générer une invitation dans les agendas afin de revoir une action (Improver) :
Création de la nouvelle clé
Génération de la clé
URL de la requête pour générer comme contenu l’export des actions (élément du module Improver)
Informations de l’export des actions
Génération d’un workflow automatisé pour récupérer cette donnée et créer un événement du type invitation dans le calendrier afin de revoir les actions en retard
Exemple d'invitation générée
