API

English

API

La cartographie peut être modifiée ou mise à jour via une REST API.

Une API REST (Representational State Transfer) est une interface de programmation d'application qui respecte les contraintes du style d'architecture REST et permet d'interagir avec les services web RESTful.

Installer l'API sur Mercator

pour installer l'API dans Mercator, il est nécessaire d'installer Passport en lançant cette commande :

php artisan passport:install

l'environnement Docker prend en charge cette fonctionnalité nativement, via le l'entrypoint.

Les APIs

Pour chaque objet du modèle de données de la cartographie, il existe une API. La liste des API se trouve dans le fichier /route/api.php

Vue du RGPD

/api/data-processings
/api/security-controls

Vues de l'écosystème

/api/entities
/api/relations

Vue métier du système d'information

/api/macro-processuses
/api/processes
/api/activities
/api/operations
/api/tasks
/api/actors
/api/information

Vue des applications

/api/application-blocks
/api/applications
/api/application-services
/api/application-modules
/api/databases
/api/fluxes

Vue de l'administration

/api/zone-admins
/api/annuaires
/api/forest-ads
/api/domaine-ads
/api/admin-users

Vue de l'infrastructure logique

/api/networks
/api/subnetworks
/api/gateways
/api/external-connected-entities
/api/network-switches
/api/routers
/api/security-devices
/api/dhcp-servers
/api/dnsservers
/api/clusters
/api/logical-servers
/api/logical-flows
/api/certificates
/api/vlans

Vue de l'infrastructure physique

/api/sites
/api/buildings
/api/bays
/api/physical-servers
/api/workstations
/api/storage-devices
/api/peripherals
/api/phones
/api/physical-switches
/api/physical-routers
/api/wifi-terminals
/api/physical-security-devices
/api/wans
/api/mans
/api/lans
/api/links
/api/fluxes

Actions gérées par le contrôleur de ressources

Les requêtes et URI de chaque api est représentée dans le tableau ci-dessous.

Requête	URI	Action
GET	/api/objets	renvoie la liste des objets
GET	/api/objets/{id}	renvoie l'objet
POST	/api/objets	sauve un nouvel objet
PUT/PATCH	/api/objets/{id}	met à jour l'objet
DELETE	/api/objets/{id}	supprimer l'objet

Les champs à fournir sont ceux décrits dans le modèle de données.

Droits d'accès

Il faut s'identifier avec un utilisateur de l'application Mercator pour pouvoir accèder aux API. Cet utilisateur doit disposer d'un rôle dans Mercator qui lui permet d'accéder / modifier les objets accédés par l'API.

Lorsque l'authentification réussi, l'API envoie un "access_token" qui doit être passé dans l'entête "Authorization" de la requête de l'API.

Liaison entre les objets

Les objets de la cartographie peuvent faire référence à d'autres objets. Par exemple, nous pouvons lier une processus à une application. Supposons que nous ayons un "processus" qui utilise deux applications "app1" et "app2". Pour ce faire, nous suivons ces étapes :

Étape 1 : Assurez-vous d'avoir l'application_id pour les applications que vous souhaitez lier.

{
  "id": 201,
  "name": "app1",
  "description": "desc1"
}
{
  "id": 202,
  "name": "app2",
  "description": "desc2"
}

Étape 2 : Liez le processus aux applications. Soit avec une mise à jour, soit avec un enregistrement, nous pouvons ajouter :

{
  "id": 101,
  "name": "processus",
  "application_id[]": [201, 202]
}

Les noms de tous les champs supplémentaires sont : ['actors', 'tasks', 'activities', 'entities', 'applications', 'informations', 'processes', 'databases', 'logical_servers', 'modules', 'domainesForestAds', 'servers', 'vlans', 'lans', 'mans', 'wans', 'operations', 'domaine_ads', 'application_services', 'certificates', 'peripherals', 'physical_servers', 'physical_routers', 'network_switches', 'routers', 'physicalSwitches', 'physicalRouters'].

Exemples

Voici quelques exemples d'utilisation de l'API avec PHP :

Authentification

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
        CURLOPT_URL => "http://127.0.0.1:8000/api/login",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => http_build_query(
            array("email" => "admin@admin.com",
                  "password" => "password")),
        CURLOPT_HTTPHEADER => array(
            "accept: application/json",
            "content-type: application/x-www-form-urlencoded",
        ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);
    $info = curl_getinfo($curl);

    curl_close($curl);

    if ($err) {
        set_error_handler($err);
    } else {
        if ($info['http_code'] == 200) {
            $access_token = json_decode($response)->access_token;

        } else {
            set_error_handler("Login to api faild status 403");
            error_log($responseInfo['http_code']);
            error_log("No login api status 403");

        }
    }

    var_dump($response);

Liste des utilisateurs

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
        CURLOPT_URL => "http://127.0.0.1:8000/api/users",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "GET",
        CURLOPT_POSTFIELDS => null, // here you can send parameters
        CURLOPT_HTTPHEADER => array(
            "accept: application/json",
            "Authorization: " . "Bearer" . " " . $access_token . "",
            "cache-control: no-cache",
            "content-type: application/json",
        ),
    ));


    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    var_dump($response);

Récupérer un utilisateur

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
        CURLOPT_URL => "http://127.0.0.1:8000/api/users/1",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "GET",
        CURLOPT_POSTFIELDS => null, // here you can send parameters
        CURLOPT_HTTPHEADER => array(
            "accept: application/json",
            "Authorization: " . "Bearer" . " " . $access_token . "",
            "cache-control: no-cache",
            "content-type: application/json",
        ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    var_dump($response);

Mettre à jour un utilisateur

<?php
   $curl = curl_init();

    curl_setopt_array($curl, array(
        CURLOPT_URL => "http://127.0.0.1:8000/api/users/8",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_POST => true,
        CURLOPT_CUSTOMREQUEST => "PUT",
        CURLOPT_POSTFIELDS => http_build_query(
            array(
                'name' => 'Henri',
                'email' => 'henri@test.fr',
                'language' => 'fr',
                'roles[0]' => 1,
                'roles[1]' => 3,
                'granularity' => '3')
            ),
        CURLOPT_HTTPHEADER => array(
            "accept: application/json",
            "Authorization: " . "Bearer" . " " . $access_token . "",
            "cache-control: no-cache",
        ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    var_dump($response);

Python

Voici un exemple d'utilisation de l'API en Python

#!/usr/bin/python3

import requests

vheaders = {}
vheaders['accept'] = 'application/json'
vheaders['content-type'] = 'application/x-www-form-urlencoded'
vheaders['cache-control'] = 'no-cache'

print("Login")
response = requests.post("http://127.0.0.1:8000/api/login",
    headers=vheaders,
    data= {'email':'admin@admin.com', 'password':'password'} )
print(response.status_code)

vheaders['Authorization'] = "Bearer " + response.json()['access_token']

print("Get workstations")
response = requests.get("http://127.0.0.1:8000/api/workstations", headers=vheaders)
print(response.json())
print(response.status_code)

bash

Voici un exemple d'utilisation de l'API en ligne de commande avec CURL et JQ

# valid login and password
data='{"email":"admin@admin.com","password":"password"}'

# get a token after correct login
token=$(curl -s -d ${data} -H "Content-Type: application/json" http://localhost:8000/api/login | jq -r .access_token)

# query users and decode JSON data with JQ.
curl -s -H "Content-Type: application/json" -H "Authorization: Bearer ${token}" "http://127.0.0.1:8000/api/users" | jq .