«Programmabilité», «Python», «RESTfull», «API», sont des termes qui reviennent souvent.
Aruba a fait des API et de la programmabilité sa force. Par exemple, les produits suivants supportent les API et disposent d’une documentation complète qui reprend l’ensemble des méthodes supportées, le format des données et les informations retournées :
- ArubaOS Switches,
- Mobility Master 8.X,
- Airwave,
- ClearPass,
- VAN SDN Controller,
- ALE,
- Aruba Central.
Vous l’aurez compris, nous allons parler API et Scripting Python.
L’objectif de cet article est de vous donner une vue générale sur les RESTfull API et de vous fournir les outils nécessaires pour construire un environnement de test qui vous permettra de faire des test d’appels API vers le ClearPass.
Qu’est-ce qu’une architecture API RESTfull Web Service ?
D’abord, commençons par définir qu’est-ce qu’un Service Web? Un Service Web est le moyen de communication entre deux systèmes ou applications via une interface prédéfinie (API). Il existe deux principaux types de Services Web : REST (le plus répandu aujourd’hui) et SOAP.
Sans rentrer dans les détails (ce n’est pas notre objectif) REST (REpresentational State Transfert) est un modèle d’architecture qui permet de définir des applications et rendre toutes les ressources de ces applications accessible via une URL. Il est implémenté en utilisant HTTP.
Une API (Application Programming Interface) est une collection de règles qui décrivent le moyen et les mécanismes d’interaction entre ces applications.
Ce qui suit tend à donner une vue générale d’un design API et les principaux éléments à connaitre pour une intégration réussie :
API Authentification :
En général, les API nécessitent une authentification car elles permettent l’accès à des ressources protégées. Il existe plusieurs méthodes pour authentifier et autoriser les accès API :
- Aucune authentification: la ressource Web API est publiquement accessible. En général pour des appels GET (en lecture).
- Basic HTTP : un nom d’utilisateur et mot de passe est ajouté en paramètre de la requête HTTP à chaque appel API.
- Auth-Token : Ce Token est généré depuis le WEB API Serveur (par exemple, depuis ClearPass) et placé dans chaque appel API. Ce token est précédé par un mot clé qui diffère selon les serveurs WEB API (exemple : ClearPass utilise le mot clé "Bearer"). Ceci permet aussi de gérer la durée de validité du Token.
- OAuth 2.0 : OAuth est un protocole libre qui permet de générer un « Access Token » depuis un serveur d’autorisation. En résumé, il permet d’autoriser une application client à utiliser une API sécurisée d’une autre application pour le compte d’un utilisateur. Il permet aussi de gérer la durée de vie du Token, de le révoquer ou de le prolonger et une gestion des sessions.
API URL
Pour faire des appels API, il faut spécifier l’URL de la ressource qu’on veut atteindre. Cette URL est disponible dans la documentation API de chaque application. Par exemple : l’URL suivante : https://<Adresse IP du ClearPass>/api/guest permet d’atteindre la base Guest qui contient tous les comptes visiteurs dans ClearPass.
Méthodes HTTP :
L’ensemble des méthodes supportées par HTTP, par exemple :
- GET: pour récupérer une ressource,
- POST: pour modifier une ressource,
- PUT: pour créer une ressource,
- DELETE: pour supprimer une ressource.
Le Payload ou Data:
C’est la donnée envoyée ou recherchée par un appel API. Elle est présentée sous différents formats les plus connus sont Extensible Markup Language (XML) ou JavaScript Object Notation(JSON).
En résumé, RESTfull API utilise les méthodes HTTP pour manipuler les données depuis/vers un serveur et retourne (selon le type de la requête) ces données sous format JSON ou XML.
Comment cela fonctionne ?
Exemple : je veux interroger l’API Guest de mon ClearPass pour récupérer l'ensemble des comptes Guest. Le schéma ci-dessous résumé la requête et la réponse que je souhaite avoir.
Comment se présente une requête REST API
Pour faire une requête ou appel REST API, il faut spécifier les éléments suivants :
- Spécifier la méthode : GET, POST, PUT, DELETE,
- Spécifier l’URL : par exemple: https://<AdresseIP_ClearPass>/api/guest
- Spécifier l’authentification : Aucune, Basic HTTP, OAuth, Auth-Token,
- Personnaliser les Headers : HTTP headers.
- Corps de la requête (Optionnel) : JSON ou XML pour compléter la requête.
Quelle est la réponse REST
La réponse correspond aux codes de statuts HTTP :
Le schéma ci-dessous représente un exemple d’une requête API REST :
Préparation de l’environnement de test
Maintenant, que nous avons une idée plus claire sur ces API…. si nous faisions un Test d’appel API vers ClearPass.
J’utilise les outils suivants pour mon environnement de test :
- PyCharm : j’utilise PyCharm comme éditeur de text (IDE) pour mes scripts Python, mais vous pouvez utiliser d’autres IDE (Notepad++, Atom, Sublime text , …). PyCharm est disponible :https://www.jetbrains.com/pycharm/
Exemple 1 : Utiliser Postman pour afficher les comptes Guest de ClearPass
En utilisant Postman, je vais afficher l’ensemble des comptes Guest sur ClearPass. L’anatomie de mon appel API est :
- Méthode : GET
- URL : https://<adressIP ClearPass>/api/guest
- Header : Token à insérer
Pour rappel, la documentation API de ClearPass est disponible à l’adresse suivante: https://<adressIP ClearPass>/api-doc
La capture d’écran suivante représente la réponse obtenue:
Exemple 2 : Utiliser un script Python pour afficher les comptes Guest de ClearPass :
Nous allons utiliser le script Python suivant pour afficher l’ensemble des comptes Guest :
import requests
import json
import argparse
import pprint
url = "https://10.14.120.30:443/api/guest" #URL de mon ClearPass
token="ad06e7c39776163163f12d3eaa6d9090063f2066"#Remplacer par le Token généré depuis ClearPass
headers={'Authorization':'Bearer ' + token}
response= requests.get(url, headers=headers ,verify=False)
response_json = response.json() #réponse sous format JSON
pprint.pprint(response_json) #utiliser la commande pretty Print pour afficher le résultat
En résumé, nous avons vu d’une manière générale ce que c’est une architecture RESTfull API et comment faire des appels API (ici vers ClearPass) en utilisant Postman et Python.
Alors « To API or not to API »……..
A bientôt……..