Module 2 : Fondamentaux des API REST et de l'embarqué

De la CLI à l’API

Limites de la configuration manuelle

• pas de traçabilité (lien avec le Module 1 : Git versionne, l’API applique),
• pas de reproductibilité ni de mise à l’échelle,
• risque d’erreur humaine élevé.

Plan de gestion

• Plan de management : accès à l’équipement pour le configurer (CLI, API, GUI),
• Plan de contrôle : décisions de routage/filtrage,
• Plan de données : trafic réel traversant l’équipement.

L’automatisation agit sur le plan de management.

L’API REST/JSON-RPC ne touche que le plan de management, jamais directement le plan de données.

Principes REST

Définition

REST (REpresentational State Transfer) est un style d’architecture pour exposer des ressources via HTTP.

• chaque ressource est identifiée par une URL (ex. /ip/address),
• les opérations utilisent les verbes HTTP :

Chaque requête HTTP est indépendante (stateless) et porte un verbe mappé à une opération CRUD.

Codes de statut HTTP

Stateless et idempotence

• Stateless : chaque requête contient toute l’information nécessaire, le serveur ne garde pas de session.
• Idempotent : répéter la requête produit le même résultat (GET, PUT, DELETE sont idempotents ; POST ne l’est pas).

Formats et protocoles

JSON

Format d’échange léger, structuré en clé/valeur :

{
  "address": "192.168.10.1/24",
  "interface": "ether1"
}

JSON-RPC

Protocole d’appel de procédure à distance encodé en JSON, utilisé par certains équipements (OpenWrt ubus, Arista eAPI) au lieu du modèle REST pur :

{
  "jsonrpc": "2.0",
  "method": "network.interface.get_status",
  "params": ["lan"],
  "id": 1
}

REST vs JSON-RPC : REST organise l’API autour de ressources et de verbes HTTP ; JSON-RPC organise l’API autour d’appels de méthodes, généralement via une seule URL (souvent en POST).

Deux façons d’organiser une API : ressources multiples + verbes (REST) vs endpoint unique + méthode dans le corps (JSON-RPC).

Authentification et sécurité

Méthodes d’authentification

Authorization: Basic YWRtaW46cGFzc3dvcmQ=
Authorization: Bearer <token>

Même besoin de part et d’autre, quatre mécanismes différents selon l’équipement (Module 2, TP5 à TP8).

TLS

• chiffre les échanges (HTTPS),
• les équipements réseau utilisent souvent un certificat auto-signé en laboratoire → vérification à désactiver uniquement en environnement de test :

requests.get(url, verify=False)  # laboratoire uniquement

Attention : ne jamais désactiver la vérification TLS (verify=False) en production.

Bonnes pratiques côté client

Sessions et timeouts

import requests

session = requests.Session()
session.auth = ("admin", "password")
response = session.get("https://192.168.1.1/rest/ip/address", timeout=5, verify=False)

• réutiliser une session évite de ré-authentifier à chaque appel,
• toujours fixer un timeout pour éviter un blocage indéfini.

Gestion des erreurs

response = session.get(url, timeout=5, verify=False)
response.raise_for_status()  # lève une exception si code >= 400
data = response.json()

Secrets hors du dépôt

Les identifiants et clés API ne doivent jamais être écrits en dur dans le code : utiliser un fichier .env (ignoré par Git, cf. Module 1) et une bibliothèque comme python-dotenv.

from dotenv import load_dotenv
import os

load_dotenv()
password = os.getenv("DEVICE_PASSWORD")

À retenir

• REST : ressources + verbes HTTP + codes de statut, stateless.
• JSON-RPC : appel de méthode encapsulé en JSON, alternative fréquente sur l’embarqué.
• Toujours authentifier, chiffrer (TLS) et garder les secrets hors du code versionné.
• Gérer explicitement timeouts et erreurs HTTP côté client.