API REST et RESTCONF

Définition

Une API REST est une interface web par laquelle une application manipule des ressources via HTTP : chaque ressource a une URL, chaque action un verbe HTTP, chaque échange un statut de réponse. RESTCONF est l'application de ce style aux équipements réseau model-driven (RFC 8040) : il expose la configuration et l'état structurés par YANG sur HTTPS, avec les mêmes verbes mais un vocabulaire de ressources imposé par le modèle de données.

Contexte

Le blueprint 200-301 v1.1, topic 6.5 (et 6.8 pour la reconnaissance des capacités), demande de décrire les caractéristiques des API REST : types d'authentification, opérations CRUD, verbes HTTP, encodage des données. Les faits à retenir : la table verbe/opération/codes de statut, la différence PUT/PATCH/POST, ce que signifient 200, 201, 400, 401, 404, 500, les en-têtes Content-Type et Accept, et ce que RESTCONF ajoute au REST ordinaire.

CRUD, verbes, statuts

Le mapping CRUD (Create, Read, Update, Delete) sur les verbes HTTP est le cœur du topic :

Opération CRUD	Verbe	Sémantique RESTCONF	Codes attendus
Create	POST	Créer une ressource sous une collection	201 Created, 400, 409 Conflict
Read	GET	Lire une ressource ou une collection	200 OK, 404 Not Found
Update	PUT	Remplacer la ressource intégralement	204/200, 400
Update partiel	PATCH	Modifier seulement les champs du payload	200/204, 400
Delete	DELETE	Supprimer la ressource	204 No Content, 404

Les codes de statut se lisent par famille : 2xx succès, 3xx redirection, 4xx erreur du client, 5xx erreur du serveur. Les six à connaître : 200 (requête traitée, payload suit), 201 (ressource créée, l'URL est dans l'en-tête Location), 400 (payload ou syntaxe invalide, relire le message d'erreur), 401 (non authentifié : mauvais identifiants ou absence de jeton), 403 (authentifié mais non autorisé), 404 (la ressource n'existe pas : URL erreur ou objet supprimé), 500 (le serveur a planté, le problème est du côté de l'appareil ou du contrôleur). PUT et PATCH se distinguent finement : PUT remplace tout ce qui n'est pas fourni (risque d'écraser un champ oublié), PATCH ne touche que les champs présents. POST sur une collection peut aussi créer avec un nom fourni par le serveur.

En-têtes et authentification

Deux en-têtes négocient les formats : Accept déclare ce que le client veut recevoir, Content-Type déclare ce que le corps contient. En RESTCONF, les valeurs sont application/yang-data+json ou application/yang-data+xml : le suffixe indique l'encodage des données modelées (cf. ). Côté authentification, deux modèles reviennent à l'examen :

• Basic : Authorization: Basic base64(user:motdepasse). Simple, mais les identifiants sont réutilisables et lisibles une fois décodés ; uniquement acceptable sur HTTPS avec rotation des comptes.
• Token/jeton : le client s'authentifie d'abord (souvent POST vers un endpoint dédié), reçoit un jeton à durée de vie limitée, et le présente dans Authorization: Bearer <jeton>. Le jeton expire, est révocable, et ne circule jamais sous forme de mot de passe vers chaque appel.

Les API Meraki et DNA Center fonctionnent sur ce principe de clé/jeton ; IOS XE accepte le basic sur son endpoint RESTCONF.

REST vs RESTCONF

Un API REST « générique » (une plateforme SaaS par exemple) invente ses URLs et ses schémas pour chaque service. RESTCONF normalise ce que YANG interdit d'inventer : les chemins dérivent des modules (/restconf/data/ietf-interfaces:interfaces), les en-têtes portent le binding du modèle, et les erreurs suivent un format d'exception YANG commun à tous les fabricants. Autrement dit : REST est un style d'architecture, RESTCONF est un protocole qui applique ce style à des données modelées.

Activation sur IOS XE (ex. routeur CSR ou Catalyst 9000) :

R1(config)# ip http secure-server
R1(config)# ip http authentication local
R1(config)# username admin privilege 15 secret MaSecret1!
R1(config)# restconf

Premiers appels, avec les IP de documentation (RFC 5737) comme dans les labs DevNet :

# Lire toutes les interfaces (GET, 200 attendu)
curl -k -u admin:MaSecret1! \
  -H "Accept: application/yang-data+json" \
  https://198.51.100.5/restconf/data/ietf-interfaces:interfaces

# Lire une seule interface (le nom est un key du noeud liste)
curl -k -u admin:MaSecret1! \
  -H "Accept: application/yang-data+json" \
  https://198.51.100.5/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

# Modifier un champ (PATCH, 204 No Content attendu) : description de l'interface
curl -k -u admin:MaSecret1! -X PATCH \
  -H "Content-Type: application/yang-data+json" \
  -d '{"ietf-interfaces:interface": {"name": "GigabitEthernet1", "description": "Lien uplink campus", "type": "iana-if-type:ethernetCsmacd", "enabled": true}}' \
  https://198.51.100.5/restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet1

Sans -k, curl rejette le certificat auto-signé par défaut d'IOS XE ; sans l'en-tête Accept correct, l'appareil répond 406 (format non négociable). La racine /restconf/data/ précède toujours le chemin YANG ; /restconf/yang-library-version et /restconf/schemas exposent les capacités du modèle.

Exemple concret chiffré

Un inventaire de 60 routeurs IOS XE est audité deux façons. Méthode CLI attendue : un script expect ouvre une session SSH, envoie show interfaces | json, lit la sortie ; 2,8 s par device, soit 168 s pour les 60, et 4 sessions échouent chaque nuit sur des prompts variables selon les versions. Méthode RESTCONF : 60 GET parallèles (8 fils) vers /restconf/data/ietf-interfaces:interfaces sur TCP 443, 610 ms par appel, audit complet en 5 secondes, zéro échec de parsing puisque la réponse est du JSON typé par YANG. Le coût de bascule : 1 commande restconf par device et un compte de service limité par ACL, contre 40 heures de maintenance du script expect sur l'année écoulée. C'est l'arithmétique que le blueprint veut faire reconnaître : même information, deux fiabilités.