Introduction

L'API fournie par les écouteurs est de type REST ; elle fonctionne donc par l'intermédiaire des différentes méthodes du protocole HTTP:

• GET : Obtenir des informations sur un objet, ou la liste des objets
• PUT : Créer ou modifier un objet
• POST : Modifier un objet
• PATCH : Modifier un objet
• DELETE : Supprimer un objet

L'identifiant des objets est fournie dans l'URL et les données supplémentaires, quand cela est  nécessaire, sont fournies dans le corps de la requête HTTP sous la forme d'un objet JSON.

Notez que cet écouteur ne permet de travailler que sur les hôtes.

Cette page décrit le format des URL ainsi que les différentes actions réalisables.

Format des URL

Les exemples utilisent la commande curl, disponible dans la plupart des distributions Linux ; cependant la requête HTTP peut être réalisée avec l'outil de votre choix.

Une requête est composée de plusieurs éléments :

• Méthode HTTP : l'action que l'écouteur doit effectuer ; les actions disponibles sont décrites en détail dans les sections suivantes
• Adresse et port d'écoute de l'écouteur : l'adresse est celle du Synchronizer, le port du listener REST fourni avec Shinken Entreprise est le 7761
• Nom du listener : il s'agit du nom de l'écouteur tel que défini dans la propriété listener_name du fichier de définition de l'écouteur ; le listener fourni avec Shinken Entreprise est listener-rest
• Version du protocole : dans cette version de Shinken Entreprise, il s'agit de la v1 ; si le protocole évolue dans de futures versions, le numéro de version évoluera également, ce qui permettra a l'écouteur de conserver la compatibilité avec la version actuelle
• Type d'objet Shinken : le type d'objet Shinken traité par la requête. Actuellement, seuls les hôtes sont gérés.
• Header HTTP : La liste des en-têtes HTTP ; dans le cas de l'écouteur ; nous spécifions que nous envoyons du contenu JSON
• Données de l'objet : Les données décrivant l'objet à importer respectent le format JSON. Il s'agit d'un dictionnaire décrivant toutes les propriétés de l'objet ; Elles sont définies de la même manière que dans les fichiers CFG et décrites sur cette page.

Description des actions

Dans ces différents exemples, nous utilisons des requêtes non authentifiées, sans le SSL et lancées depuis le serveur hébergeant le Synchronizer.

Obtenir la liste des hôtes créés par l'écouteur

Cette URL associée à la méthode GET, permet d'obtenir la liste de tous les éléments présents dans l'écouteur. Le format de retour est un JSON

Cet appel correspond à l'onglet "Liste des éléments enregistrés dans la base de données" sur la page de description de votre source.

$ curl "http://localhost:7761/shinken/listener-rest/v1/hosts/" -X GET | python -m json.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   785  100   785    0     0   104k      0 --:--:-- --:--:-- --:--:--  109k
[
    {
        "_SE_UUID": "core-hosts-22b48e7408a549f6895badada2fd3690",
        "_SSH_KEY_PASSPHRASE": "root",
        "_SSH_USER": "root",
        "_SYNC_KEYS": "core-hosts-22b48e7408a549f6895badada2fd3690,hote-example",
        "_id": "22b48e7408a549f6895badada2fd3690",
        "host_name": "hote-example",
        "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
        "update_date": 1527839180.6257291,
        "use": "linux"
    },
    {
        "_SE_UUID": "core-hosts-bafe4fae3fc447b992daa3f10ee260f2",
        "_SYNC_KEYS": "core-hosts-bafe4fae3fc447b992daa3f10ee260f2,hote-example-2",
        "_id": "bafe4fae3fc447b992daa3f10ee260f2",
        "address": "192.168.0.42",
        "host_name": "hote-example-2",
        "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
        "update_date": 1527839954.469449,
        "use": "shinken-full"
    }
]

Créer un hôte

Pour mener à bien cette action, vous pouvez utiliser les méthodes PUT  qui permettent d'envoyer à l'écouteur un nouvel objet

• Lors de la création d'un nouvel objet, l'écouteur renvoie l'identifiant de l'objet créé sous la forme "core-hosts-<ID>" . Cet identifiant devra être utilisé lors d'autres opérations manipulant l'objet :
  
  

$  curl "http://localhost:7761/shinken/listener-rest/v1/hosts"  -X PUT -d '{ "host_name": "hote-example", "use":"linux", "_SSH_USER":"root", "_SSH_KEY_PASSPHRASE":"root" }'
"core-hosts-22b48e7408a549f6895badada2fd3690"

Obtenir les données d'un hôte

La méthode GET, lorsqu'elle est accompagnée d'un identifiant, l'objet est renvoyé au format JSON.

$ curl "http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-22b48e7408a549f6895badada2fd3690" -X GET | python -mjson.tool
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   381  100   381    0     0  72668      0 --:--:-- --:--:-- --:--:-- 76200
{
    "_SE_UUID": "core-hosts-22b48e7408a549f6895badada2fd3690",
    "_SSH_KEY_PASSPHRASE": "root",
    "_SSH_USER": "root",
    "_SYNC_KEYS": "core-hosts-22b48e7408a549f6895badada2fd3690,hote-example",
    "_id": "22b48e7408a549f6895badada2fd3690",
    "host_name": "hote-example",
    "imported_from": "listener-rest envoy\u00e9 depuis l'adresse 127.0.0.1",
    "update_date": 1527839180.6257291,
    "use": "linux"
}

Modifier un hôte

• Pour modifier un objet existant, utilisez la méthode POST en indiquant son identifiant dans l'URL. Les propriétés présentes dans l'objet JSON transmis dans la requête remplaceront ou compléteront alors celles se trouvant dans l'objet. Les autres propriétés ne sont pas modifiées.
  
  

  $ curl "http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-22b48e7408a549f6895badada2fd3690" -X POST -d '{ "address": "192.168.1.42" }' done

  
  

• Pour réécrire totalement un objet existant, utilisez la méthode PUT en indiquant son identifiant dans l'URL. Les propriétés présentes dans l'objet actuel seront supprimées et l'hôte sera recréé avec le même identifiant que l'ancien. Cela correspond à une requête DELETE et une requête PUT avec un identifiant spécifique.

  $ curl -X PUT http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-22b48e7408a549f6895badada2fd3690 -d '{ "host_name": "hote-example", address": "192.168.1.42" }' done

  
  

Supprimer un hôte créé par l'écouteur

Utilisez l'action DELETE pour supprimer un objet créé par l'écouteur, en fournissant l'identifiant de l'objet à supprimer.

$ curl -u 'root:root' -X DELETE http://localhost:7761/shinken/listener-rest/v1/hosts/core-hosts-22b48e7408a549f6895badada2fd3690
done

Question fréquentes sur l'import d'éléments via l'API REST

Forcer l'utilisation d'un modèle

Lorsqu'on importe un hôte existant qui contient la propriété "use", la liste des modèle décrits dans la propriété "use" est ajoutée à la liste des modèles actuellement utilisée par l'hôte.

Comme lors de l'import d'hôtes via fichiers Cfg, il est possible de forcer l'utilisation d'une liste de modèles (remplacement et non ajout de modèles) en utilisant la propriété "use[FORCE]" au lieu de "use".

Plus de précisions sur l'utilisation du FORCE pour les modèles sont disponible dans la page de documentation suivante: Syntaxe des fichiers d imports