Guide de développement Canopsis¶
Vous trouverez ici toute la documentation nécessaire au développement autour de Canopsis.
Documentation des API¶
Canopsis repose sur un ensemble d'API REST (voir une définition), pour son fonctionnement interne et pour son interfaçage avec d'autres programmes.
Ces API ont connu 4 versions différentes. L'APIv4 est la version actuelle.
APIv4¶
La documentation des APIv4 edition community est disponible par le biais de Swagger-community.
La documentation des APIv4 edition pro est disponible par le biais de Swagger-pro.
Ces nouvelles API suivent l'OpenAPI Specification 2.0.
Important
Les API REST imposent aux clients de respecter la spécification HTTP, et notamment de prendre en charge toute redirection HTTP qui serait envoyée par l'API.
Une erreur courante, par exemple avec l'outil curl (est sa bibliothèque), est que certains clients HTTP n'activent pas la prise en charge des redirections HTTP par défaut, ce qui est incorrect. Veillez donc à toujours utiliser les options de type curl -L en ligne de commande (ou l'option CURLOPT_FOLLOWLOCATION dans sa bibliothèque) afin de vous interfacer correctement avec l'ensemble des API REST.
Note
Il est possible d'activer la documentation swagger de la version installée en ajoutant l'option -docs aux options de démarrage du binaire canopsis-api.
Une url /swagger/index.html sera ainsi accessible et disponible derrière le port d'écoute de l'api ( par défaut TCP/8082 )
Anciennes API¶
Les anciennes API v1 ou v2 ne sont plus utilisées par les dernières versions de Canopsis, et n'ont donc plus lieu d'être utilisées ou documentées.
URL de l'API¶
L'API Canopsis peut être interrogée sur plusieurs URL différentes :
http(s)://<canopsis>/api/v4/: via le reverse-proxy Nginx (avec les en-têtes CORS)http://<canopsis>:8082/api/v4/: moteurcanopsis-apidirectement (sans les en-têtes CORS)
Warning
Depuis Canopsis 4.4, l'URL http(s)://<canopsis>/backend/api/v4/ est dépréciée. Pensez à mettre à jour vos scripts et applications clients de celle-ci.
Remplacer
<canopsis>par l'adresse IP ou le nom de domaine du Canopsis déployé.
Si l'API est interrogée via un navigateur (Firefox, Chrome, Safari, etc) ou un framework emulant un navigateur (Angular, Electron, etc) et pour lesquels en-têtes CORS sont nécessaires, alors il faut utiliser l'URL du reverse-proxy Nginx.
L'usage de l'URL du moteur canopsis-api est possible pour des requêtes dites "classiques", par exemple via des scripts, via l'outil curl ou encore via des webhooks de solutions externes.
Authentification¶
Authentification basique HTTP¶
L'API Canopsis supporte l'authentification basique HTTP.
Exemple :
curl -X GET -u "user:mdp" -H "Content-Type: application/json" "http://localhost:8082/api/v4/cat/healthcheck/status"
Authentification par token¶
Il est possible d'utiliser un jeton (token) d'authentification pour manipuler l'API.
Ce jeton s'obtient grâce à une authentification sur la route /api/v4/login.
Le jeton est ensuite passé dans un entête Authorization:Bearer {{ token }}.
Exemple :
Obtention du jeton
curl -X POST -H "Content-Type: application/json" -d '{"username" : "mon_user", "password" : "mon_pass"}' "http://localhost:8082/api/v4/login"
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJjYW5vcHNpcyIsImlzcyI6ImNhbm9wc2lzIiwiZXhwIjoxNjc2MTk2Nzk5LCJpYXQiOjE2NzM1MTgzOTksImp0aSI6ImFiNWM3MTllLWY2YzktNGI1ZS05MTQ4LWZkZWRjN2NkMjM3YiJ9.5tV7L9K-sBswjyXjO8aOQFMwor_LqoGacvg5RuBF51A"}
Utilisation du jeton
curl -X GET -H "Content-Type: application/json" -H "Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJjYW5vcHNpcyIsImlzcyI6ImNhbm9wc2lzIiwiZXhwIjoxNjc2MTk2Nzk5LCJpYXQiOjE2NzM1MTgzOTksImp0aSI6ImFiNWM3MTllLWY2YzktNGI1ZS05MTQ4LWZkZWRjN2NkMjM3YiJ9.5tV7L9K-sBswjyXjO8aOQFMwor_LqoGacvg5RuBF51A" "http://localhost:8082/api/v4/cat/healthcheck/status"
Note
Le jeton peut être soumis à un délai d'expiration.
RDV dans le profil de l'utilisateur dont vous souhaitez utiliser le jeton.
Clé d'authentification / Authkey¶
Canopsis permet une authentification à l'API par authkey.
Cette authkey, disponible pour tout utilisateur enregistré dans Canopsis, est utilisable directement dans l'URL d'API appelée ou
en tant qu'entête d'une requête vers l'API.
Note
Vous pouvez récupérer la clé d'authentification d'un utilisateur depuis l'interface graphique.
Dans l'URL / querystring
Dans ce cas, il vous suffit d'ajouter le paramètre authkey dans l'URL.
Exemple avec la commande cURL :
curl -X GET -H "Content-Type: application/json" "http://localhost:8082/api/v4/cat/healthcheck/status?authkey=5ba7537d-132d-49e1-8581-8c057de2b558"
Entête (headers)
La clé d'authentification peut également être passée en tant qu'entête de la requête HTTP à l'API.
Le nom de l'entête est dans ce cas x-canopsis-authkey.
Exemple avec la commande cURL :
curl -X GET -H "Content-Type: application/json" -H "x-canopsis-authkey: 5ba7537d-132d-49e1-8581-8c057de2b558" "http://localhost:8082/api/v4/cat/healthcheck/status"