Introduction à l’utilisation de l’API Cyberwatch

Les utilisateurs de Cyberwatch ont accès à une API permettant d’interagir avec la majeure partie des ressources visibles dans l’application. Cet accès peut permettre par exemple l’automatisation de certaines tâches, ou l’obtention de résultats personnalisés…

Cette page constitue une introduction au fonctionnement et à l’utilisation de cette API.

Authentification

L’utilisation de l’API, quelque soit la route interrogée, nécessite d’être authentifié par les clés d’API d’un utilisateur Cyberwatch ayant un rôle Administrateur.

Ces clés d’API peuvent être générées depuis la GUI Cyberwatch, dans l’onglet Mon Profil > Clés d’API, de chaque Administrateur Cyberwatch.

Ces identifiants peuvent-être utilisés via les deux mode d’authentifications proposés : le basic-auth et l’apiAuth. Nous documentons l’usage de curl, de la cmdlet PowerShell Invoke-WebRequest, ou notre client d’API Python. Le mode d’authentification privilégié dans les exemples de notre documentation est le basic-auth. Plus d’informations concernant l’apiAuth sont disponibles ici.

S’authentifier auprès de l’API et tester sa connexion

Les commandes référencées ci-dessous vous permettent de tester la validité de l’identifiant utilisé et effectuent un test de communication avec votre API cyberwatch. En cas de succès, un id utilisateur vous est retourné.

N.B Cette interrogation ne nécessite qu’un identifiant d’API disposant des droits de lecture seule. Il peut donc par la suite être nécessaire de vérifier le niveau d’accès dont dispose l’identifiant utilisé en fonction des requêtes qui seront effectuées.

Vous trouverez ci-joint des exemples détaillés de l’exécution de ce test de connexion via curl, la cmdlet PowerShell Invoke-WebRequest, ou notre client d’API Python.

Structures des retours et interrogation de l’API

Les différents points d’accès de l’API, sont consultables depuis un Swagger accessible depuis votre application via le bouton </> situé en haut à gauche de la page.

Depuis Swagger, chaque section décrit la route utilisée ainsi que la liste des paramètres disponibles et un exemple de la structure de données retournées par la requête. Il est d’ailleurs possible de générer la liste en question au format OpenAPI depuis depuis ici, afin de l’importer dans d’autres outils comme Postman. Swagger vous permet aussi de générer directement des requêtes curl authentifiées et de les exécuter à la volée, afin de tester les retours API de votre instance.

Comme pour toute requête faite à l’API, Swagger nécessite d’être authentifié via un identifiant d’API comme indiqué précédemment.

Nous vous recommandons de les configurer directement via le bouton “Authorize” de Swagger. Lorsque les identifiants sont ainsi fournis, Swagger génère directement le header d’authentification curl, ce qui rend la commande facilement réutilisable.

Supports des clients d’API

Notre ancienne documentation d’API, comme nos anciens clients d’API PowerShell et Python, moins permissifs, ne sont plus supportés.

Ces documentations sont remplacées par nos documentions d’API pour curl, PowerShell,et Python.

Pour toute question sur le sujet, ou besoin d’accompagnement sur la migration d’un script d’API d’une ancienne version vers la nouvelle, vous pouvez nous contacter par e-mail à support@cyberwatch.fr, ou par téléphone au +33 1 84 80 88 84.