Aperçu

L' REST API fournie par l'outil de gestion des services Matrix42 (ESM) permet l'intégration de toute application externe à la solution Matrix42 . Cette REST API respecte les contraintes et les principes REST pour permettre l'accès aux données dans ESM. Toutes les fonctionnalités d'administration du système et du modèle de données sont exclues de l'interface REST API .

Comment commencer

REST API peut être activée dans tout environnement Matrix42 dont l'outil de gestion des services Matrix42 (ESM) est mis à jour vers la version 2021.4 ou ultérieure. Pour ce faire, il est nécessaire de demander une licence REST API auprès de Matrix42 . Cette licence activera le module API externe Matrix42 dans le système. Ce dernier doit également disposer d'un utilisateur technique (local) et d'un rôle défini pour la gestion des accès.

Accès à l'environnement

Tous les points de terminaison liés à REST API sont accessibles depuis [base_url]/rest-api/itsm/:versionCode (par exemple : Matrix42 ) dans les environnements cloud et depuis [base_url]/itsm/api/:versionCode.
Veuillez noter que REST API n'est pas prise en charge dans les déploiements sur site (installation Windows + base de données MS SQL ). Vous pouvez facilement tester l'accès à la documentation Swagger REST API avec votre navigateur : l'interface utilisateur Swagger est accessible à l'adresse [base_url]/rest-api/itsm/v1/docs/swagger/index.html (par exemple : Matrix42 ).

Licence

L'environnement doit disposer d'une licence REST API . Une fois la licence installée et ESM redémarré, l'administrateur peut vérifier que l' API externe Matrix42 figure parmi les modules activés dans la section « État du système et informations d'exécution » de la vue Administration.

Enregistrement

Les appels REST API seront consignés dans un fichier nommé « integration.log », accessible via l'interface d'administration ESM. Ce journal répertorie toutes les opérations effectuées sur l' REST API .
ESM enregistre également les statistiques dans un fichier journal séparé appelé « Matrix42 », également disponible via la vue d'administration ESM.

2023-04-11 20:34:00,635|Usage,consumed,1000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-12 04:54:00,643|Usage,consumed,2000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-12 13:30:00,743|Usage,consumed,3000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-12 21:50:00,573|Usage,consumed,4000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-13 06:10:00,548|Usage,consumed,5000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-13 14:30:00,606|Usage,consumed,6000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-13 22:50:00,882|Usage,consumed,7000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-14 07:10:00,737|Usage,consumed,8000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-14 15:30:01,055|Usage,consumed,9000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-14 23:50:00,690|Usage,consumed,10000,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-17 00:00:00,144|Usage,consumed,15779,rejected,0,since,2023-04-11T11:51:27+0300
2023-04-17 00:00:00,145|Statistics reset

L'extrait ci-dessus est un exemple du fichier « rest_api_usage.log ». Ce journal fournit des statistiques hebdomadaires sur les appels REST API avec des résultats positifs et négatifs, et un récapitulatif en fin de semaine. Ces appels réussis sont également appelés transactions REST API .

Utilisateurs

Pour authentifier les requêtes via l' REST API , l'outil de gestion des services Matrix42 requiert un compte utilisateur local (et non le compte EIM utilisé dans l'environnement cloud pour les connexions). Il est recommandé de créer un utilisateur distinct pour chaque intégration utilisant l' REST API . Vous devez également créer un rôle disposant des autorisations nécessaires pour utiliser API externe et attribuer ce rôle à l'utilisateur local.
La création d'un compte valide peut se faire en suivant les étapes suivantes :

1. Créez un rôle et sélectionnez l'autorisation du module API externe Matrix42 .
2. Ajouter les autorisations de dossier au rôle.
3. Ajouter les autorisations de modèle au rôle.
4. Créer un utilisateur REST - API .
5. Ajouter l'utilisateur au rôle précédemment créé.
6. Vérifiez que vous pouvez obtenir un jeton JWT à partir du point de terminaison de connexion.

Authentification

API REST utilise des jetons JWT Bearer pour l'authentification, obtenus via un point de terminaison de connexion dédié. Une fois créé, le jeton est valide pendant une durée prédéfinie, configurable dans les paramètres de la plateforme ESM (security.external.api.token.expiration.time ). La durée d'expiration par défaut est de 15 minutes. Ces jetons ne sont pas bloquants : un compte peut donc en générer autant que nécessaire.

Une requête POST peut être utilisée pour obtenir le jeton JWT :

https://instance. Matrix42 cloud.com/rest-api/itsm/v1/users/login

L'identifiant et le mot de passe doivent figurer dans le corps de la requête. Si l'identifiant et le mot de passe sont valides, le serveur répond avec un jeton JWT dans les en-têtes.

Depuis la version 2022.3.0.2 d'ESM, le jeton est également renvoyé dans le corps :
{
"code": 200,
"message": "Token issued.",
"timestamp": "2022-10-13T10:14:15Z",
"token": "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJURVNUX1JFU1RBUEkiLCJpc3MiOiJodHRwczovL2VzbXBvci5lZmVjdGVjbG91ZC1kZXYuY29tL2l0c20vYXBpL3YxL3VzZXJzL2xvZ2luIiwiaWF0IjoxNjY1NjU2MDU1LCJleHAiOjE2NjU2NTY5NTV9.aO2Td-62f2QYNszZhc9rbM-MOs_zhZvnRuJXK28CLIApmj_p6O0oL7Dy623QsRZwR3AWrajzQ96uKYgFxzxvwg"
}

Lors des requêtes ultérieures adressées à d'autres points de terminaison, le jeton doit être inclus dans l'en-tête Authorization (dans un format similaire à celui renvoyé) pour l'autorisation. Par exemple, la récupération de tous les incidents pourrait ressembler à ceci (avec curl) :

GET "https:// Matrix42 cloud.com/rest-api/itsm/v1/dc/incident/data" -H "accept: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJUcnlpbmcgdG8gZGVjb2RlIG91ciB0b2tlbnM_IiwiaWF0IjoxNjM4MzcyODM1LCJleHAiOjE2Njk5MDg4MzUsImF1ZCI6Ind3dy5leGFtcGxlLmNvbSIsInN1YiI6IlRoYXQncyBnb29kLCB5b3Ugc2hvdWxkIGFsd2F5cyB0aGluayBhYm91dCBzZWN1cml0eS4ifQ.zzdHvo6VvqN08-YCtylWQCQjcKI7L9TCgHWplOgnNXY

Outils

Swagger

Swagger , un outil permettant d'interagir avec l' API et de consulter la documentation, est inclus dans tous les environnements disposant d' API licence REST valide. L'interface utilisateur Swagger est accessible via l'URL suivante : base_url/rest-api/itsm/v1/docs/swagger/index.html (par exemple : Matrix42 ).
Swagger génère une documentation basée sur la spécification Open API 3.0, qui peut également être téléchargée depuis l'interface utilisateur (base_url/rest-api/itsm/v1/docs/openapi.json) et importée dans divers outils d'intégration et de test.

Paramètres

Les paramètres suivants relatifs à l' REST API peuvent être ajustés dans l'outil de gestion des services Matrix42 . Veuillez noter que ces paramètres servent à garantir que les intégrations n'impactent pas négativement les performances du système. Il est déconseillé d'augmenter leurs valeurs, car cela pourrait entraîner une charge excessive du système.