Commandes de base pour une API Express avec exemples pratiques : un playbook d’exploitation

Intro

Ce guide montre comment exploiter une API Express en toute sécurité avec des commandes concrètes et minimales. Vous passerez de l’observation à un changement vérifié, avec des exemples exécutables en local ou dans des environnements proches de la production. L’accent est mis sur la sécurité opérationnelle : observer d’abord, limiter le rayon d’impact, utiliser des espaces réservés plutôt que des secrets, vérifier les résultats, et documenter comment revenir en arrière si l’état attendu n’est pas atteint.

Portée et public : développeurs, ingénieurs DevOps et équipes de startup qui exploitent des APIs Express sous Node.js. Les exemples visent Express 4.x/5.x sur Node.js LTS et fonctionnent avec des déploiements courants (node local, PM2, systemd, Docker). Remplacez les espaces réservés comme <PORT> et <SERVICE_NAME> par vos propres valeurs.

Inventaire des versions et de l’environnement

Objectif : capturer ce qui tourne, où et comment, avec des commandes en lecture seule avant tout changement.

Prérequis :

Node.js LTS (v18 ou ultérieur recommandé) et npm
curl ou httpie pour les vérifications HTTP
Accès au répertoire de l’application (<PROJECT_DIR>) ou au conteneur/orchestrateur

Enregistrer les versions et horodatages

# Horodatage (notez-le dans vos notes de changement)
date -u

# Versions de Node et npm
node -v
npm -v

# Version d’Express dans le projet courant
cd <PROJECT_DIR>
npm ls express --depth=0 || echo "Express not installed here"

# Version de l’application (depuis package.json)
node -p "require('./package.json').version" 2>/dev/null || echo "No package.json version"

Identifier la topologie et le runtime

Processus node local :

ps aux | grep node | grep <PROJECT_DIR> | grep -v grep
lsof -i :<PORT> -sTCP:LISTEN || ss -lntp | grep :<PORT>

PM2 :

pm2 status
pm2 describe <SERVICE_NAME>
pm2 logs <SERVICE_NAME> --lines 50

systemd :

systemctl status <SERVICE_NAME>.service
journalctl -u <SERVICE_NAME>.service -n 100 --no-pager

Docker :

docker ps --filter "name=<SERVICE_NAME>"
docker logs <CONTAINER_ID> --tail 100

docker inspect <CONTAINER_ID> --format '{{json .NetworkSettings.Ports}}' | jq

Observations API en lecture seule

Commencez par des endpoints qui ne changent pas l’état. Si vous n’avez pas encore d’endpoints de santé, ajoutez-les ensuite via le Chemin de configuration sécurisé.

# Remplacez par votre hôte/port et la route
curl -sS -D - http://localhost:<PORT>/health || echo "Health not reachable"

# Voir le code de statut et le timing
curl -sS -o /dev/null -w "status=%{http_code} time=%{time_total}\n" http://localhost:<PORT>/health

Définissez votre résultat attendu et un signal d’échec avant d’agir. Exemple : 200 OK en moins de 100 ms attendu; échec = connexion refusée, délai d’attente, ou 5xx.

Notes de sécurité :

Gardez les identifiants, tokens et URLs de services hors de l’historique du terminal. Utilisez des variables d’environnement comme $DB_URI et ne collez jamais de vrais secrets dans la documentation ou les tickets.
Ne redémarrez pas et ne redéployez pas pendant l’inventaire. Le but est d’apprendre, pas de changer.

Chemin de configuration sécurisé

Objectif : faire le plus petit changement justifié, le vérifier, et disposer d’un chemin de retour testé.

Changement exemple A : ajouter des endpoints opérationnels basiques (/health, /ready, /version) sans exposer de secrets.

Prérequis :

Vous contrôlez <PROJECT_DIR>
Vous pouvez redémarrer le processus (PM2/systemd/Docker) avec un impact minimal

Observer l’état actuel

# Baseline : latence et statut
curl -sS -o /dev/null -w "status=%{http_code} time=%{time_total}\n" http://localhost:<PORT>/health

Faire le changement minimal

app.js (ou server.js) :

const express = require('express');
const pkg = require('./package.json');

const app = express();
const PORT = process.env.PORT || 3000;

// Limite de taille de corps sécurisée; ajustez au besoin
app.use(express.json({ limit: process.env.JSON_LIMIT || '1mb' }));

// Endpoints de santé : lecture seule, aucun secret
app.get('/health', (req, res) => res.status(200).json({ status: 'ok' }));
app.get('/ready', (req, res) => {
  // Optionnel : vérifier les dépendances (ping DB, cache). Renvoyer 503 si non prêt.
  res.status(200).json({ ready: true });
});
app.get('/version', (req, res) => res.json({ name: pkg.name, version: pkg.version }));

app.listen(PORT, () => {
  console.log(`API listening on :${PORT}`);
});

Vérifier le résultat

# Redémarrage via PM2
pm2 restart <SERVICE_NAME> && pm2 logs <SERVICE_NAME> --lines 20

# Ou systemd
sudo systemctl restart <SERVICE_NAME>.service
sudo systemctl status <SERVICE_NAME>.service --no-pager

# Ou Docker Compose
docker compose up -d --no-deps --build <SERVICE_NAME>

echo "HEALTH:";  curl -sS -D - http://localhost:<PORT>/health -o /dev/null | head -n 1
echo "READY :";  curl -sS -D - http://localhost:<PORT>/ready  -o /dev/null | head -n 1
echo "VER  :";  curl -sS http://localhost:<PORT>/version | jq

Résultat attendu : /health et /ready renvoient 200, /version renvoie les champs name et version.

Chemin de reprise

Si le processus ne démarre pas : annulez le changement de code (git restore), redéployez et confirmez que l’état revient à la ligne de base.
Si un seul endpoint échoue (ex. /ready à cause d’un contrôle de dépendance) : renvoyez temporairement un 200 statique et créez une tâche de suivi pour implémenter des vérifications de disponibilité plus complètes.

Changement exemple B : configurer un CORS strict pour une seule origine.

const cors = require('cors');
app.use(cors({ origin: process.env.CORS_ORIGIN || 'https://app.example.com', methods: ['GET','POST','PUT','DELETE','OPTIONS'] }));

Vérification :

# Vérification du pré-vol (preflight)
curl -sS -i -X OPTIONS \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: GET" \
  http://localhost:<PORT>/health | sed -n '1,10p'

Retour arrière : supprimez la ligne du middleware CORS et redémarrez, ou définissez CORS_ORIGIN sur une valeur sûre.

Vérification et diagnostics

Objectif : confirmer le comportement de manière objective et isoler rapidement les problèmes en utilisant d’abord des outils en lecture seule.

Contrôles au niveau HTTP

# Statut + timing
curl -sS -o /dev/null -w "status=%{http_code} time=%{time_total}\n" http://localhost:<PORT>/health

# En-têtes et aperçu du corps
curl -sS -D - http://localhost:<PORT>/version | sed -n '1,20p'

# Validité JSON
curl -sS http://localhost:<PORT>/version | jq type

Erreurs de routage et de type de contenu

Signaux fréquents :

404 Not Found : chemin erroné ou base URL incorrecte. Vérifiez l’enregistrement de la route et le chemin de montage.
415 Unsupported Media Type : le client a omis l’en-tête Content-Type. Essayez :

curl -sS -X POST http://localhost:<PORT>/items \
  -H 'Content-Type: application/json' \
  -d '{"name":"demo"}' -i

Diagnostics CORS

# La requête OPTIONS (preflight) doit renvoyer 204/200 et les en-têtes Access-Control-Allow-*
curl -sS -i -X OPTIONS \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  http://localhost:<PORT>/items | sed -n '1,20p'

Processus et journaux

# PM2
pm2 logs <SERVICE_NAME> --lines 50

# systemd
journalctl -u <SERVICE_NAME>.service -n 100 --no-pager

# Docker
docker logs <CONTAINER_ID> --tail 100

Conflits de port et écoute

# Vérifier si le port est déjà utilisé
lsof -i :<PORT> -sTCP:LISTEN || ss -lntp | grep :<PORT>

Si le port est utilisé et que vous ne pouvez pas arrêter l’autre service, définissez un nouveau PORT dans l’environnement et redémarrez votre API.

Modes de panne et reprise

EADDRINUSE : address already in use

Signal : erreur au démarrage mentionnant EADDRINUSE.
Correctif : identifier le processus en conflit et choisir un nouveau port ou arrêter le service en conflit.

lsof -i :<PORT>
# Reprise plus sûre : changer le PORT
export PORT=<NEW_PORT>
pm2 restart <SERVICE_NAME>

503 sur /ready mais /health renvoie 200

Signal : l’état de disponibilité dépend d’un service en aval (base de données, cache) non atteignable.
Correctif : vérifiez séparément la connectivité de la dépendance tout en gardant /health au vert.

# Exemple de test TCP DB (remplacez hôte/port)
nc -zv <DB_HOST> <DB_PORT> || echo "DB not reachable"

Reprise : filtrez le trafic au load balancer sur /ready jusqu’au rétablissement de la dépendance.

413 Payload Too Large lors d’un POST JSON

Signal : les clients reçoivent 413 pour des requêtes volumineuses.
Correctif : augmentez prudemment la limite de taille du corps.

app.use(express.json({ limit: process.env.JSON_LIMIT || '5mb' }));

Vérifiez avec une charge de test; revenez en arrière en restaurant la limite précédente.

Unhandled promise rejections provoquant des crashs

Signal : le processus sort de manière intermittente, les journaux mentionnent unhandledRejection.
Correctif : journaliser et gérer les rejets; utilisez un gestionnaire de processus pour redémarrer automatiquement.

process.on('unhandledRejection', (err) => {
  console.error('unhandledRejection', err);
});

Reprise : déployez la correction de journalisation, surveillez; si l’instabilité persiste, revenez au dernier build stable.

Port Docker non exposé

Signal : le conteneur est sain, mais le port de l’hôte est injoignable.
Correctif : corrigez le mapping de port.

# Faux : le conteneur écoute sur 3000 mais aucun mapping sur l’hôte
# Correct :
docker run -d --name <SERVICE_NAME> -p 3000:3000 <IMAGE_TAG>

Vérifiez avec curl sur le port hôte; retour arrière en arrêtant le conteneur incorrect et en le recréant avec le mapping adéquat.

Liste de contrôle d’exploitation

À utiliser lors de la préparation ou de l’exécution d’un changement sur une API Express.

Avant tout changement :

Confirmez les composants et versions (Node, npm, Express, version de l’app).
Capturez l’état de santé actuel : codes de statut et latence pour /health et les routes clés.
Rassemblez les 100 dernières lignes de journaux et notez l’horodatage.
Identifiez la topologie de déploiement (local, PM2, systemd, Docker) et la méthode d’accès.
Définissez les critères de succès (ex. 200 sur /health, p95 < 150 ms) et les signaux d’échec.
Définissez un retour arrière (git revert, tag d’image précédent, réinitialisation de variables d’environnement).

Pendant le changement :

Touchez un seul élément à portée limitée : une variable d’environnement, un middleware, ou un mapping de port.
Ajoutez des commentaires ou messages de commit avec l’ID du changement et l’horodatage.
Évitez d’éditer plusieurs fichiers sans lien.

Après le changement :

Vérifiez les endpoints avec curl, y compris la sortie de timing.
Contrôlez les journaux pour détecter erreurs ou avertissements introduits par le changement.
Comparez la latence et le taux d’erreur à la ligne de base pré-changement.
Documentez le résultat et s’il a fallu revenir en arrière.

Bloc de vérification que vous pouvez coller dans un runbook :

set -e
BASE=http://localhost:<PORT>
for path in /health /ready /version; do
  echo "Checking $path";
  curl -sS -o /dev/null -w "$path status=%{http_code} time=%{time_total}\n" "$BASE$path";
done

Conclusion

L’exploitation d’une API Express est fiable lorsque chaque étape est limitée en version, observable et réversible. Commencez par l’inventaire et des contrôles en lecture seule, effectuez le plus petit changement qui résout un problème clair, vérifiez avec des signaux concrets (codes de statut, en-têtes, timings), et gardez un véritable plan de retour arrière prêt. Utilisez des espaces réservés au lieu de secrets, limitez le rayon d’impact à un seul élément à la fois, et documentez les résultats attendus ainsi que les étapes de reprise. Avec ce playbook, vous diagnostiquerez plus vite, appliquerez des changements plus sûrs et maintiendrez votre API Express stable en développement comme en production.