Utilisation de l'API

Ce guide couvre la fonctionnalité centrale de l’API Apprise : l’envoi de notifications. Vous pouvez envoyer des notifications de deux manières :

1. Sans état : vous fournissez les URL de configuration dans la charge utile de la requête.
2. Avec état : vous référencez une clé de configuration préalablement enregistrée.

Formats de Réponse

Par défaut, les endpoints renvoient text/plain. Si vous préférez du JSON, envoyez Accept: application/json.

Pour les endpoints de notification (/notify et /notify/{KEY}), vous pouvez aussi demander une vue HTML simple des logs avec Accept: text/html. C’est principalement utile pour des tests manuels dans un navigateur.

Notifications Sans État

Les notifications stateless sont idéales pour un usage de type « sidecar » lorsque vous ne voulez pas gérer de configuration persistante sur le serveur. Vous devez fournir le paramètre urls à chaque requête.

Requête JSON de Base

La méthode la plus courante consiste à envoyer une charge utile JSON à /notify.

Endpoint : POST /notify

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "urls": "mailto://user:pass@gmail.com",
    "body": "Backup completed successfully.",
    "title": "System Status"
  }' \
  http://localhost:8000/notify

Pièces Jointes

Pour envoyer des pièces jointes, utilisez multipart/form-data. L’API accepte les uploads de fichiers classiques ainsi que les URL distantes. Utilisez attach comme nom de champ recommandé. Les alias attachment et attachments sont également acceptés.

Pour les charges utiles JSON qui fournissent des pièces jointes distantes ou encodées, utilisez les mêmes noms de champ.

# Uploader un fichier local
curl -X POST \
    -F "urls=discord://webhook_id/token" \
    -F "body=See attached log." \
    -F "attach=@/var/log/syslog" \
    http://localhost:8000/notify

# Référencer une URL distante (Apprise la téléchargera puis la transmettra)
curl -X POST \
    -F "urls=discord://webhook_id/token" \
    -F "body=Security Camera Snapshot" \
    -F "attach=http://camera-ip/snapshot.jpg" \
    http://localhost:8000/notify

Notifications Avec État

Les notifications stateful vous permettent de simplifier votre code client. Vous stockez une fois sur le serveur les URL complexes, associées à une clé, puis votre client référence simplement cette clé.

Endpoint : POST /notify/{KEY}

Envoyer vers une Clé

Si vous avez enregistré une configuration sous la clé my-alerts :

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Database connection failed",
    "type": "warning"
  }' \
  http://localhost:8000/notify/my-alerts

Tags

Les configurations stateful prennent en charge les tags, ce qui vous permet de notifier des sous-groupes spécifiques de vos URL enregistrées.

La valeur passée dans le champ tag suit les règles suivantes :

Valeur tag	Services sélectionnés
"TagA"	Possède TagA
"TagA TagB"	Possède TagA ET TagB
"TagA+TagB"	Possède TagA ET TagB
"TagA&TagB"	Possède TagA ET TagB
"TagA,TagB"	Possède TagA OU TagB
"TagA|TagB"	Possède TagA OU TagB
"TagA TagC,TagB"	Possède (TagA ET TagC) OU TagB

# Notifier les services tagués "devops" OU "admin"
curl -X POST -d '{"tag": "devops,admin", "body": "..."}' ...

# Notifier les services tagués "devops" ET "critical"
curl -X POST -d '{"tag": "devops critical", "body": "..."}' ...

# Notifier les services correspondant à ('comment' ET 'create') OU 'admin'
curl -X POST -d '{"tag": "comment create,admin", "body": "..."}' ...

Mapping du Payload (Hooks)

Parfois, vous ne pouvez pas changer le format du payload envoyé par un outil tiers (par ex. Grafana, Prometheus). L’API Apprise permet de faire correspondre les champs entrants avec les champs compatibles Apprise via des paramètres de requête préfixés par deux-points (:).

Note

Les clés de mapping passent dans la query string et doivent être encodées URL si elles contiennent des caractères spéciaux.

Règles de Mapping

Syntaxe	Effet
?:incoming_field=apprise_field	Renomme incoming_field vers le champ Apprise
?:incoming_field=	Supprime incoming_field du payload
?:apprise_field=literal value	Force apprise_field à une chaîne fixe

Exemple — votre outil envoie {"message": "Server Down", "severity": "high"}, mais Apprise attend body et type :

curl -X POST \
  -d '{"message": "Server Down", "severity": "high"}' \
  "http://localhost:8000/notify/my-alerts?:message=body&:severity=type"

Mapping de Champs Imbriqués

Lorsque le payload entrant utilise des objets imbriqués ou des tableaux, référencez-les côté source de la règle avec une notation pointée pour les objets imbriqués et une notation entre crochets pour les éléments de tableau. Les deux peuvent être combinés librement.

Objets Imbriqués (Notation Pointée)

Utilisez un chemin séparé par des points pour parcourir des dictionnaires imbriqués :

# Payload provenant d'un outil de supervision :
# { "event": { "title": "CPU spike", "state": "critical" },
#   "component": { "name": "web-server-01" } }
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"event":{"title":"CPU spike","state":"critical"},"component":{"name":"web-server-01"}}' \
  "http://localhost:8000/notify/my-alerts?:event.title=title&:event.state=type&:component.name=body"

Éléments de Tableau (Notation entre Crochets)

Ajoutez [N] juste après le nom de clé pour déréférencer l’index N dans ce tableau. Les indices multiples et le mélange avec la notation pointée sont pris en charge :

# Payload provenant d'un webhook forum / gestion de projet (ex. Scoold / Para) :
# { "items": [ { "title": "New post", "objectURI": "https://example.com/q/1234" } ] }
curl -g -X POST \
  -H "Content-Type: application/json" \
  -d '{"items":[{"title":"New post","objectURI":"https://example.com/q/1234"}]}' \
  "http://localhost:8000/notify/my-alerts?:items[0].title=title&:items[0].objectURI=body"

Note

curl traite les crochets dans les URL comme une syntaxe de globbing ; -g (ou --globoff) est donc requis lorsque vous utilisez des chemins de mapping tels que items[0].title. Gardez l’URL entre guillemets afin que le shell la transmette telle quelle.

Les indices chaînés permettent de traverser des tableaux imbriqués :

# Clé source           Ce à quoi elle correspond
items[0]               premier élément du tableau items
items[0].objectURI     propriété .objectURI du premier élément