API d'administration de DEX-X

API d'administration de DEX-X

Introduction

L’API REST DEX à été introduite à partir de la version 10.6.6, permettant ainsi l'utilisation des méthodes HTTP pour administrer DEX ( récupérer, modifier, créer et supprimer des données dans DEX).
La configuration de l'API REST est nécessaire afin d'interagir avec le référentiel de DEX via le protocole HTTP.  Afin de sécuriser les échanges, un jeton de type JWT est nécessaire aux requêtes HTTP.
Il est donc nécessaire de configurer DEX dans un premier temps afin de valider ce jeton.

JWT ( JSON Web Token ) : JWT est un standard ouvert (RFC 7519) qui définit une manière compacte et autonome de transmission sécurisée d’informations entre les parties sous la forme d’un objet JSON. il permet ainsi de contrôler l’accès aux données protégées de façon fiable.

Note : La génération de Jeton d'identité (JWT) doit être faite indépendamment de DEX

Configuration de DEX

La configuration se fait depuis l'interface Web -> Administration, dans la rubrique "serveur web" puis dans la sous partie Paramètres API REST.
Il est nécessaire de charger la clé publique du certificat ( certificat à générer en amont) qui sera utilisée pour la génération des jetons JWT. Seul les certificats ayant le format X509 sont pris en charge. Il est possible d'activer différents niveaux de contrôle du jeton JWT, que sont le nom du fournisseur, l'audience ou les origines autorisées.

Note  : l'activation de l'option "Autoriser les connexions anonymes" est requis pour utiliser l'API d'administration, sous peine de voir s'afficher une pop-up d'authentification

Depuis l'interface Web -> administration -> gestion du serveur web

Note : Le certificat doit contenir un nom d'utilisateur valide dans les utilisateurs DEX


Vous pouvez vérifier les informations du jeton depuis le site jwt.io comme ci-dessous



Configuration du client

Il est nécessaire de paramétrer le client afin que celui-ci ajoute à la requête HTTP une entête spécifique "authorization" avec en paramètre le type "bearer" et le jeton JWT.

Afin de faciliter l'utilisation de l'API, une documentation swagger est disponible sous l'url de DEX en ajoutant l'extension "/api" à l'URL DEX (Ex : http://localhost/dex/api/index.html). Cette documentation liste l'ensemble des actions ainsi que le format des messages que supporte l'API.
Une version json est disponible / accessible depuis la page HTML de la documentation swagger, le lien est visible en dessous du titre DEX-X API.

Swagger

Il est possible d'effectuer des tests directement depuis le site du swagger intégré à DEX ou via Postman.
Pour se faire, il faut :
  1. Se rendre sur le site avec l'URL :   http://localhost/dex/api/index.html
  2. S'authentifier à l'aide du bouton Authorize, visible à droite. Il faut ajouter "bearer" avant le token



Note : La modification de données via l'api DEX necessaite l'arret de l'ordonnanceur

Exemples requêtes 

Ordonnanceur
  1. Renvoi la liste de l'ensemble des environnements
  2. Requête : {serveur}api/env/
  3. Ex : http://localhost/dex/api/env
  4. Params :
  5. Methode : GET

  1. Renvoi les informations sur l'environnement
  2. Requête : {serveur}api/env/{monenv}
  3. Ex : http://localhost/dex/api/env/prod
  4. Params :
  5. Methode : GET

  1. Permet de modifier le statut d'un environnement
  2. Requête : {serveur}api/env/{envId}/broker/{status}
  3. http://localhost/dex/api/env/prod/broker/pause
  4. Params :
  5. Methode : PUT
  6. Status : "stop","start","pause"
  7. Env : "design","qa","prod","env4","env5",..etc

Flux
  1. Renvoi la liste de l'ensemble des flux d’un environnement
  2. Requête : {serveur}/api/env/{envId}/Flows
  3. Ex : http://localhost/dex/api/env/prod/Flows
  4. Params :
  5. Methode : PUT
  6. Env : "design","qa","prod"

  1. Renvoi les informations liées à un flux
  2. Requête : {serveur}/api/env/{envId}/Flows/{ID}
  3. Ex :  http://localhost/dex/api/env/prod/Flows/09c005cf-939d-4560-90e4-efb847a7a34f
  4. Params :
  5. Methode : GET
  6. Env : "design","qa","prod"
  7. Id : "id"

  1. Mise à jour des informations d'un flux 
  2. Requête : {serveur}/api/env/{envId}/Flows/{ID}
  3. Ex :
  4. http://localhost/dex/api/env/prod/Flows/09c005cf-939d-4560-90e4-efb847a7a34f
  5. Body : 
  6. {
            "id": "09c005cf-939d-4560-90e4-efb847a7a34f",        
            "comment": "Ceci est une modification depuis l'API DEX - 2022-06-17T11:36:47.04",
            "isActive": false,
            "isMultipleExecution": false,
            "isLogDetailed": false,
            "maxMultipleExecution": 1,
            "timeoutInSeconds": 3600,
            "priority": 6        
    }
  7. Params :
  8. Methode : PUT
  9. Env : "design","qa","prod"
  10. Id : "id"

  1. Suppresion de flux par le nom
  2. Requête : {serveur}/api/env/{envId}/Flows/{FlowName}/{eTag}
  3. Ex :
  4. http://localhost/dex/api/env/prod/Flows/NomDuFlux/09c005cf-939d-4560-90e4-efb847a7a34f

  6. Params :
  7. Methode : DELETE
  8. Env : "design","qa","prod"
  9. Flow Name : "Nom du Flux"
  10. Id : "etag id"


Planifications (Triggers)
  1. Permet de récupérer la liste des triggers d'un flux 
  2. Requête : /api/env/{envId}/Flows/{flowId}/Triggers/{triggerId}
  3. Ex :  http://localhost/dex/api/env/prod/Flows/16299856-4d79-4872-9bb1-0b7f83b8c90c/Triggers/ba57228a-a608-454d-ba18-3b301aa4d798
  4. Params :
  5. Methode : PUT
  6. Env : "design","qa","prod","env4","env5",..etc
  7. envid / flowid / triggerid 

  1. Permet de récupérer la liste des triggers d'un flux
  2. Requête : /api/env/{envId}/Flows/{flowId}/Triggers/
  3. Ex :  http://localhost/dex/api/env/prod/Flows/16299856-4d79-4872-9bb1-0b7f83b8c90c/Triggers/
  4. Params :
  5. Env : "design","qa","prod","env4","env5",..etc
  6. Methode : GET

  1. Permet de récupérer les informations sur la planification d'un trigger sur un flux
  2. Requête : /api/env/{envId}/Flows/{flowId}/Triggers/{triggerId}/Schedulers
  3. Ex :  http://localhost/dex/api/env/prod/Flows/16299856-4d79-4872-9bb1-0b7f83b8c90c/Triggers/ba57228a-a608-454d-ba18-3b301aa4d798/Schedulers
  4. Params :
  5. Env : "design","qa","prod","env4","env5",..etc
  6. Methode : GET

  1. Permet de mettre à jour les informations d'une planification 
  2. Requête : /api/env/{envId}/Flows/{flowId}/Triggers/{triggerId}/Schedulers/{id}
  3. Ex :  http://localhost/dex/api/env/prod/Flows/16299856-4d79-4872-9bb1-0b7f83b8c90c/Triggers/ba57228a-a608-454d-ba18-3b301aa4d798/Schedulers/4ea993ba-dbb3-412b-bab4-dd7a3e48ccf7
  4. Body :
  5. {      
            "dayOfWeekList": [
                "Sunday",
                "Monday",
                "Tuesday",
                "Wednesday",
                "Thursday",
                "Friday",
                "Saturday"
            ],
            "id": "a01f9dd0-4cb9-4814-84f0-173325560ec7",
            "name": "Nom de ma planification",
            "comment": "Modification depuis API DEX",
            "isActive": true,
            "triggerId": "21285045-0dd9-461a-a5f5-e42e5ed2c372",
            "validityPeriods": [],
            "useAlertNoEvent": false,
            "alertNoEventContactList": [],
            "timeInterval": 10,
            "timeUnit": 0,
            "timeSlots": [
                {
                    "startTime": "00:00:00",
                    "endTime": "23:59:59"
                }
            ],
            "calendarType": "DayOfWeekList"    
       
    }
  6. Params :
  7. Methode : PUT
  8. Env : "design","qa","prod"
  9. flowid/triggerid/id


Exemples détaillés visibles sur le site du swagger  http://localhost/dex/api/index.html.

Fin