Recettes d'utilisation de l'API

Cette page est orientee taches : chaque recette est un flux complet a adapter, et non une simple liste de points de terminaison. Pour le catalogue complet des endpoints et tous les champs, voir la reference API HTTP Webserver. Pour des identifiants longue duree, voir Creer des jetons d’API.

Tous les exemples ciblent l’API REST du Webserver sur le port 8050 et supposent que vous disposez d’un jeton. L’interface Swagger interactive sur https://<webserver>:8050/docs/index.html est le moyen le plus rapide de decouvrir la forme des requetes et des reponses pendant le developpement.

Avant de commencer : modeles d’authentification

Il existe deux facons de s’authentifier ; le bon choix depend de la duree de vie de votre automatisation.

Pour tout traitement non surveille, generez une cle d’API une fois et stockez-la dans votre gestionnaire de secrets — n’integrez jamais un mot de passe dans un pipeline.

# One-time: generate a 1-year automation key (returns a token string)
curl -k -X POST https://<webserver>:8050/genAPIKey \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"cicd-pipeline","ttl":"8760","group":"admin"}'

Recette 1 — Un assistant d’authentification reutilisable

Toutes les autres recettes s’appuient dessus. Il recupere un jeton, echoue vite si la connexion est rejetee, et expose un assistant call().

#!/bin/bash
set -euo pipefail

WEBSERVER="https://webserver.example.com:8050"
CACERT="/path/to/webserver.crt"   # or replace --cacert "$CACERT" with -k for testing

# Authenticate once and cache the token for the script's lifetime.
TOKEN=$(curl -s --cacert "$CACERT" -X POST "$WEBSERVER/api/auth" \
  -H "Content-Type: application/json" \
  -d '{"username":"automation","password":"'"$MNS_PASSWORD"'"}' \
  | jq -r '.token')

if [ -z "$TOKEN" ] || [ "$TOKEN" = "null" ]; then
  echo "Authentication failed" >&2
  exit 1
fi

# Thin wrapper: call <METHOD> <PATH> [curl args...]
call() {
  local method="$1"; local path="$2"; shift 2
  curl -s --cacert "$CACERT" -X "$method" "$WEBSERVER$path" \
    -H "Authorization: Bearer $TOKEN" "$@"
}

# Example: list components
call GET /api/components | jq .

Recette 2 — Onboarding en masse de moniteurs URL depuis un CSV

Vous disposez d’une liste de points de terminaison a surveiller et ne voulez pas cliquer dans l’interface pour chacun. Parcourez un CSV et faites un POST /api/urls par ligne.

Avec urls.csv :

name,url,probe,sched
Homepage,https://www.example.com,probe-paris,5MIN
Login API,https://api.example.com/health,probe-paris,1MIN
Docs,https://doc.example.com,probe-london,15MIN

# Reuses TOKEN and call() from Recipe 1.
tail -n +2 urls.csv | while IFS=, read -r name url probe sched; do
  echo "Creating monitor: $name"
  call POST /api/urls \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "'"$name"'",
      "url": "'"$url"'",
      "probe": "'"$probe"'",
      "sched": "'"$sched"'",
      "state": "on",
      "tags": "Production,Imported",
      "threshCri": "5000",
      "threshMaj": "3000",
      "threshMin": "1500",
      "emailOnF": "true",
      "emailR": "ops@example.com"
    }' | jq -r '.message // .'
done

Le meme schema fonctionne pour tout type de moniteur — remplacez /api/urls par /api/tcps, /api/pings, /api/apis, et ajustez les champs du corps. Voir la reference pour les champs de chaque type.

Recette 3 — Construire une page de statut personnalisee depuis l’API

Affichez votre propre tableau de bord, digest Slack ou resume terminal en interrogeant les endpoints de statut. Chaque type de moniteur expose /status (tous) et /ko (uniquement ceux qui ne sont pas OK).

# Print a one-line health summary across every monitor type.
for type in urls apis monitors tcps pings nslookups dbs snmps syss; do
  ko=$(call GET "/api/$type/ko" | jq 'length')
  printf "%-10s %s problem(s)\n" "$type" "${ko:-0}"
done

Pour une vue au niveau application, interrogez le statut agrege de l’Application plutot que les moniteurs individuels :

# Aggregated status of every application
call GET /api/apps/status | jq -r '.[] | "\(.name): \(.status)"'

Recette 4 — Conditionner un deploiement CI/CD a la sante des moniteurs

Stoppez un deploiement si le service cible est deja en mauvaise sante, ou verifiez la sante juste apres le deploiement. Cet extrait sort avec un code non nul des qu’un moniteur portant un tag donne n’est pas OK — a inserer dans une etape de pipeline.

# Fail the pipeline if any "Checkout" URL monitor is not OK.
problems=$(call GET /api/urls/ko \
  | jq '[.[] | select(.tags | test("Checkout"))] | length')

if [ "${problems:-0}" -gt 0 ]; then
  echo "Health gate failed: $problems Checkout monitor(s) not OK" >&2
  call GET /api/urls/ko | jq -r '.[] | select(.tags | test("Checkout")) | "  - \(.display_name): \(.status)"'
  exit 1
fi
echo "Health gate passed"

Vous pouvez aussi declencher une execution a la demande juste apres un deploiement au lieu d’attendre le prochain controle planifie :

# Force an immediate run, then read the fresh result
call GET /api/urls/run/homepage-check
sleep 5
call GET /api/urls/details/homepage-check | jq '{status, responseTime}'

Recette 5 — Planifier une fenetre de maintenance avant une mise en production

Supprimez automatiquement les alertes pendant un changement planifie afin que l’equipe ne soit pas notifiee pour un redemarrage attendu. Creez un downtime sur les tags concernes, cadre par un planning cron et une duree.

# Recurring: every Sunday 02:00, 2-hour window over Production
call POST /downtime/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-maintenance",
    "display_name": "Weekly Maintenance Window",
    "tags": "Production",
    "sched": "0 2 * * 0",
    "duration": "120",
    "state": "on"
  }' | jq -r '.message // .'

Pour une mise en production ponctuelle, creez le downtime juste avant le changement et supprimez-le ensuite avec DELETE /downtime/delete/:key.

Recette 6 — Exporter un inventaire de tout ce que vous surveillez

Produisez un instantane exploitable en audit de chaque moniteur et de son statut courant — utile pour les revues, la planification de capacite ou la reconciliation avec une CMDB.

# Combine details from every monitor type into one JSON array
{ for type in urls apis tcps pings nslookups dbs snmps syss; do
    call GET "/api/$type/details" | jq --arg t "$type" '.[]? | {type:$t, name:.display_name, status:.status, probe:.probe, tags:.tags}'
  done
} | jq -s '.' > monitor-inventory.json

echo "Wrote $(jq 'length' monitor-inventory.json) monitors to monitor-inventory.json"

Travailler avec les autres composants

Le Webserver est le plan de controle, mais les sondes, integrateurs et agents de decouverte exposent chacun leur propre API. Utilisez-les lorsque vous avez besoin de donnees ou d’actions locales a un composant :

Dans la plupart des automatisations, vous ne dialoguez qu’avec le Webserver — il relaie pour vous les donnees en direct des sondes a chaque requete.

Gestion des erreurs et bonnes pratiques

• Verifiez le champ code, pas seulement le statut HTTP. Les reponses portent un code numerique (200, 400, 401, 404, 429, 500). Un 401 signifie generalement un jeton expire — reauthentifiez-vous. Voir Codes de statut.
• Respectez le verrouillage de connexion. Cinq connexions echouees depuis une IP declenchent un verrouillage 429 de 5 minutes. Mettez votre jeton en cache ; ne vous authentifiez pas a chaque appel.
• Rafraichissez avant l’expiration, n’interrogez pas en boucle. Les jetons utilisateur durent 15 minutes — appelez /refresh_token dans la fenetre pour les taches longues, ou utilisez une cle d’API longue duree.
• Privilegiez le certificat CA a -k. -k ignore la verification TLS et n’est destine qu’aux tests ; utilisez --cacert pour tout ce qui s’execute sans surveillance.
• Utilisez les tags pour cadrer l’automatisation. Pilotez les operations en masse par tags afin qu’un script ne touche que les moniteurs voulus et rien d’autre.

See also

• API HTTP Webserver — reference complete des endpoints et des champs
• Creer des jetons d’API — generer et revoquer des cles longue duree
• Cas d’usage — les scenarios produit que ces recettes automatisent
• Integrer des tableaux de bord dans un portail — publier des vues en lecture seule sans code

Traductions

• en: API usage recipes