Aller au contenu

API publique

L'API publique est l'API à utiliser pour tous les scripts, connecteurs et intégrations externes. Elle est versionnée, documentée et stable : son comportement ne change pas d'une version mineure à l'autre.

API publique et API interne

Canopsis expose deux API distinctes, servies par deux services différents :

API Préfixe Service Port par défaut Usage
API publique /api/v5 canopsis-public-api 8083 Scripts, connecteurs, intégrations
API interne /internal canopsis-internal-api 8082 Interface web de Canopsis uniquement

L'API interne sert uniquement l'interface web. Ses routes peuvent être modifiées ou supprimées à chaque version, sans préavis. N'appelez pas /internal depuis un script : tout ce dont une intégration a besoin est disponible dans l'API publique.

Période de transition : /api/v4

L'ancien préfixe /api/v4 n'est plus servi par les API. Pour ne pas casser les intégrations existantes, la configuration Nginx fournie redirige /api/v4/<chemin> vers /internal/<chemin> : un script qui passe par Nginx continue donc de fonctionner, avec les anciennes méthodes d'authentification (authkey, authentification basique, jeton obtenu par /login).

Un script qui appelle directement le service, sans passer par Nginx, ou une installation qui utilise son propre reverse proxy, doit remplacer /api/v4 par /internal, ou reproduire cette redirection.

Cette compatibilité est temporaire. Les anciennes méthodes d'authentification seront supprimées dans une prochaine version, et les routes de l'API interne évoluent avec l'interface. Migrez vos scripts vers l'API publique dès maintenant (voir Migrer un script depuis l'API v4).

Versionnement

  • Le préfixe de version (/api/v5) ne change que si une version majeure de Canopsis introduit des changements incompatibles dans l'API publique. Il passe alors à /api/v6.
  • Les corrections de bugs de l'API publique sont reportées dans les versions maintenues, sans changement de préfixe.
  • Aucune nouvelle fonctionnalité ni aucun changement de comportement n'est reporté dans une version déjà publiée.

URL de l'API

URL Usage
https://<canopsis>/api/v5/ Via le reverse proxy Nginx (recommandé)
http://<canopsis>:8083/api/v5/ Directement sur le service canopsis-public-api

GET /api/v5/ renvoie le nom, la version de l'API et le lien vers sa documentation.

Documentation Swagger

Lorsque le service canopsis-public-api est démarré avec l'option -docs, la spécification OpenAPI de l'API publique de votre instance est disponible à l'adresse /api/v5/docs/swagger.yaml.

Authentification

L'API publique s'authentifie uniquement avec un jeton d'API publique, transmis dans l'en-tête Authorization :

Authorization: Bearer <jeton>

L'authkey, l'authentification basique et les jetons obtenus par /login ne sont pas acceptés par l'API publique.

Créer un jeton

Les jetons se créent dans le menu Administration > Jetons d'accès API, onglet Jetons d'API publique :

  1. Cliquez sur Créer un jeton d'API publique.
  2. Donnez-lui un nom, par exemple celui du script ou de l'intégration qui l'utilisera.
  3. Définissez éventuellement une durée de validité.
  4. Copiez le jeton affiché : pour des raisons de sécurité, sa valeur complète ne sera plus affichée.

La liste des jetons indique leur date d'expiration et leur date de dernière utilisation. Un jeton peut être supprimé à tout moment.

Un jeton hérite des droits de l'utilisateur qui l'a créé. Créez les jetons avec un compte dédié à l'intégration, disposant uniquement des droits nécessaires.

Droits

Chaque route de l'API publique demande un droit API, le même que pour l'ancienne API : par exemple api_alarm_read pour lire les alarmes, api_event pour envoyer des événements, api_entity en lecture pour lire les entités, api_pbehavior en création pour créer un comportement périodique, ou api_acl pour gérer les utilisateurs.

Conventions

Pagination

Les listes utilisent offset et limit, et indiquent s'il reste des résultats :

{ "data": [ ... ], "meta": { "offset": 0, "limit": 50, "has_more": true } }

Le nombre total de résultats n'est pas calculé. Pour tout récupérer, augmentez offset tant que meta.has_more vaut true :

offset=0
while :; do
  body=$(curl -s -H "Authorization: Bearer $TOKEN" \
    "https://<canopsis>/api/v5/entities?offset=$offset&limit=500")
  echo "$body" | jq -c '.data[]'
  [ "$(echo "$body" | jq '.meta.has_more')" = "true" ] || break
  offset=$((offset + 500))
done

Tri

Un seul paramètre sort, sous la forme champ:sens, éventuellement répété avec des virgules : ?sort=name:asc ou ?sort=creation_date:asc,resource:desc. Sans sens, le tri est ascendant. Les champs triables dépendent de la route.

Filtres et patterns

Les filtres simples (type, catégorie, connecteur, composant, tag, dates...) sont des paramètres de la route GET. Les filtres par pattern passent par une route POST .../search, avec le pattern en JSON dans le corps de la requête :

curl -X POST "https://<canopsis>/api/v5/alarms/search" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"resolution":"open","alarm_pattern":[[{"field":"v.state.val","cond":{"type":"eq","value":3}}]]}'

La syntaxe des patterns est celle de Canopsis : le tableau extérieur est un OU, les tableaux intérieurs des ET.

Opérations en masse

Les routes /bulk/... répondent 207 Multi-Status, avec un résultat par élément, dans l'ordre de la requête :

[ { "id": "...", "status": 200 },
  { "status": 400, "errors": { "name": "The field is a required field" } } ]

Erreurs

Code Corps Signification
400 {"errors": {"<champ>": "<message>"}} Erreur de validation, par champ
401 {"error": "Unauthorized"} Jeton absent ou expiré
403 {"error": "Forbidden", "message": "..."} Le jeton n'a pas le droit nécessaire
404 {"error": "Not Found"} Objet introuvable
409 {"error": "Conflict", "message": "..."} Conflit, par exemple suppression d'un type de comportement périodique encore utilisé
413 {"error": "Request Entity Too Large"} Corps de requête trop volumineux (import)

Routes disponibles

Domaine Routes
Alarmes GET /alarms, POST /alarms/search, GET /alarms/{id}/steps
Export d'alarmes POST /alarm-exports, GET /alarm-exports/{id}, GET /alarm-exports/{id}/download
Événements POST /event
Entités GET /entities, POST /entities/search ; POST /entities/pause, POST /entities/resume ; POST /bulk/entities/pause, POST /bulk/entities/resume (voir Pause)
Export d'entités POST /entity-exports, GET /entity-exports/{id}, GET /entity-exports/{id}/download
Import d'entités POST /entity-imports, GET /entity-imports/{id}
Comportements périodiques GET, POST /pbehaviors ; GET, PUT, PATCH, DELETE /pbehaviors/{id} ; POST, PUT, PATCH, DELETE /bulk/pbehaviors
Comportements périodiques de connecteur POST, PUT, DELETE /bulk/connector-pbehaviors
Motifs et types de comportements périodiques GET, POST /pbehavior-reasons et /pbehavior-types ; GET, PUT, DELETE /pbehavior-reasons/{id} et /pbehavior-types/{id}
Utilisateurs GET, POST /users ; GET, PUT, PATCH, DELETE /users/{id} ; POST, PUT, PATCH, DELETE /bulk/users
JUnit (Pro) POST /test-reports, POST /test-screenshots, POST /test-videos

Toutes les routes sont préfixées par /api/v5. Le détail des paramètres et des réponses figure dans la documentation Swagger.

Exports asynchrones

Les exports d'alarmes et d'entités se font en trois temps : création de la tâche, suivi de son état, téléchargement du fichier. Le format est csv ou json.

job=$(curl -s -X POST "https://<canopsis>/api/v5/alarm-exports" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{
    "format":"csv","delimiter":"semicolon","resolution":"open",
    "fields":[{"name":"_id","label":"ID"},{"name":"entity.name","label":"Entité"}]
  }' | jq -r ._id)

until [ "$(curl -s -H "Authorization: Bearer $TOKEN" "https://<canopsis>/api/v5/alarm-exports/$job" | jq -r .status)" = done ]; do sleep 2; done
curl -s -OJ -H "Authorization: Bearer $TOKEN" "https://<canopsis>/api/v5/alarm-exports/$job/download"

Le téléchargement répond 404 tant que la tâche n'est pas terminée, ou si elle a échoué (status vaut alors failed).

Import d'entités

POST /entity-imports?source=<nom> importe un tableau d'entités. Le paramètre source est obligatoire : il identifie le système d'origine et est enregistré sur chaque entité importée (filtre import_source). Chaque élément porte son action (set, disable, enable, delete) : les entités absentes de l'import ne sont pas modifiées. Un seul import s'exécute à la fois.

Migrer un script depuis l'API v4

Point API v4 API publique
Préfixe /api/v4/... /api/v5/...
Authentification authkey (paramètre authkey ou en-tête x-canopsis-authkey), authentification basique, jeton /login Jeton d'API publique : Authorization: Bearer <jeton>
Pagination ?page=3&limit=50, meta.page_count, meta.total_count ?offset=100&limit=50, meta.has_more (pas de total)
Tri ?sort_by=name&sort=asc, multi_sort[] ?sort=name:asc
Patterns Paramètres d'URL (alarm_pattern=... encodé) POST .../search avec un corps JSON
Opérations en masse Chaque résultat reprend l'élément envoyé (item) Résultat par position ou par id, sans item
Alarmes opened=true\|false, tstart/tstop resolution=open\|resolved (obligatoire), time_field + from/to
Export "separator", CSV uniquement "delimiter", "format": "csv" ou "json", "resolution" obligatoire

Routes renommées :

API v4 API publique
alarm-export alarm-exports
entity-export entity-exports
PUT contextgraph-import, PUT contextgraph-import-partial POST entity-imports?source=<nom> (import partiel uniquement)
cat/junit/upload/reports, /screenshots, /videos test-reports, test-screenshots?suite_name=..., test-videos?suite_name=...

Routes sans équivalent public, et alternatives :

  • Suppression d'un comportement périodique par nom : recherchez-le, puis supprimez-le par identifiant.
  • bulk/entity-pbehaviors : utilisez bulk/connector-pbehaviors, avec des dates de début et de fin.
  • Activation et désactivation en masse des comportements périodiques ou des utilisateurs : PATCH /bulk/pbehaviors ou PATCH /bulk/users avec {"_id": "...", "enabled": false}.
  • Les paramètres propres à l'interface (active_columns[], filters[], correlation, with_*, only_bookmarks...) n'existent pas dans l'API publique.

Les utilisateurs créés par l'API publique sont des utilisateurs à authentification externe : source et external_id sont obligatoires, et il n'y a pas de champ password. Les comptes locaux se gèrent dans l'interface.