REST API

Flowguard hat eine RESTful API zum programmgesteuerten Verwalten und Ausführen von Flows.

Basis-URL

Alle API-Endpunkte haben das Präfix:

/wp-json/flowguard/v1/

Beispiel:

https://ihreseite.de/wp-json/flowguard/v1/flows

Authentifizierung

API-Endpunkte erfordern WordPress-Authentifizierung:

Für Anfragen aus dem WordPress-Admin:

Automatisch authentifiziert, wenn eingeloggt
Nonce-Verifizierung für Schreiboperationen erforderlich

Anwendungspasswörter

Für externe Anfragen:

Erstellen Sie ein Anwendungspasswort im WordPress-Benutzerprofil
Verwenden Sie HTTP-Basic-Authentifizierung
Benutzername: WordPress-Benutzername
Passwort: Anwendungspasswort

Beispiel mit cURL:

bash

curl -u 'benutzername:xxxx xxxx xxxx xxxx xxxx xxxx' \
  https://ihreseite.de/wp-json/flowguard/v1/flows

Berechtigungen

Flow-Endpunkte

Leseoperationen - Erfordert edit_posts-Berechtigung Schreiboperationen - Erfordert edit_posts-Berechtigung Ausführungsoperationen - Erfordert manage_options-Berechtigung

Einstellungs-Endpunkte

Leseoperationen - Erfordert manage_options-Berechtigung Schreiboperationen - Erfordert manage_options-Berechtigung

Flow-Endpunkte

Flows auflisten

Gibt eine Liste aller Flows zurück (verwendet den WordPress-Posts-Endpunkt).

Endpunkt:

GET /wp-json/wp/v2/flowguard-flows

Parameter:

Parameter	Typ	Beschreibung
`per_page`	integer	Anzahl Flows pro Seite (Standard: 10)
`page`	integer	Seitennummer (Standard: 1)
`search`	string	Flows nach Titel suchen
`status`	string	Nach Status filtern (publish, draft, etc.)

Antwort:

json

[
  {
    "id": 123,
    "title": {
      "rendered": "Login-Test-Flow"
    },
    "status": "publish",
    "date": "2024-12-06T10:00:00",
    "modified": "2024-12-06T15:30:00",
    "meta": {
      "_flowguard_status": "active",
      "_flowguard_steps": [...],
      "_flowguard_settings": {...},
      "_flowguard_last_run": {...}
    }
  }
]

Beispiel:

bash

curl https://ihreseite.de/wp-json/wp/v2/flowguard-flows?per_page=20

Einzelnen Flow abrufen

Gibt einen bestimmten Flow nach ID zurück.

Endpunkt:

GET /wp-json/wp/v2/flowguard-flows/{id}

Parameter:

Parameter	Typ	Beschreibung
`id`	integer	Die Flow-Post-ID

Antwort:

json

{
  "id": 123,
  "title": {
    "rendered": "Login-Test-Flow"
  },
  "status": "publish",
  "meta": {
    "_flowguard_status": "active",
    "_flowguard_steps": [
      {
        "id": "step_1",
        "type": "navigate",
        "config": {
          "url": "https://ihreseite.de/login"
        }
      }
    ],
    "_flowguard_settings": {
      "timeout": 30000,
      "retries": 0,
      "screenshot": true
    },
    "_flowguard_last_run": {
      "timestamp": "2024-12-06T15:30:00",
      "status": "passed",
      "duration": 3450,
      "error": "",
      "results": [...]
    }
  }
}

Beispiel:

bash

curl https://ihreseite.de/wp-json/wp/v2/flowguard-flows/123

Flow erstellen

Erstellt einen neuen Flow.

Endpunkt:

POST /wp-json/wp/v2/flowguard-flows

Anfragekörper:

json

{
  "title": "Neuer Test-Flow",
  "status": "publish",
  "meta": {
    "_flowguard_status": "active",
    "_flowguard_steps": [
      {
        "id": "step_1",
        "type": "navigate",
        "config": {
          "url": "https://ihreseite.de"
        }
      }
    ],
    "_flowguard_settings": {
      "timeout": 30000,
      "retries": 0,
      "screenshot": true
    }
  }
}

Antwort: Gibt das erstellte Flow-Objekt zurück (gleiches Format wie Einzelnen Flow abrufen).

Beispiel:

bash

curl -X POST https://ihreseite.de/wp-json/wp/v2/flowguard-flows \
  -H "Content-Type: application/json" \
  -d '{"title":"Neuer Flow","status":"publish"}'

Flow aktualisieren

Aktualisiert einen bestehenden Flow.

Endpunkt:

PUT /wp-json/wp/v2/flowguard-flows/{id}

Parameter:

Parameter	Typ	Beschreibung
`id`	integer	Die Flow-Post-ID

Anfragekörper: Gleiches Format wie Flow erstellen (nur zu aktualisierende Felder einschließen).

Antwort: Gibt das aktualisierte Flow-Objekt zurück.

Beispiel:

bash

curl -X PUT https://ihreseite.de/wp-json/wp/v2/flowguard-flows/123 \
  -H "Content-Type: application/json" \
  -d '{"title":"Aktualisierter Flow-Titel"}'

Flow löschen

Löscht einen Flow.

Endpunkt:

DELETE /wp-json/wp/v2/flowguard-flows/{id}

Parameter:

Parameter	Typ	Beschreibung
`id`	integer	Die Flow-Post-ID
`force`	boolean	Papierkorb umgehen und dauerhaft löschen (Standard: false)

Antwort:

json

{
  "deleted": true,
  "previous": {
    // Vorheriges Flow-Objekt
  }
}

Beispiel:

bash

curl -X DELETE https://ihreseite.de/wp-json/wp/v2/flowguard-flows/123?force=true

Flow-Ausführungs-Endpunkte

Einzelnen Flow ausführen

Führt einen bestimmten Flow aus.

Endpunkt:

POST /wp-json/flowguard/v1/flows/{id}/run

Parameter:

Parameter	Typ	Beschreibung
`id`	integer	Die Flow-Post-ID

Antwort:

json

{
  "success": true,
  "message": "Flow-Ausführung gestartet.",
  "flow": {
    "id": 123,
    "title": "Login-Test-Flow",
    "steps": [...],
    "settings": {...},
    "siteUrl": "https://ihreseite.de"
  }
}

Beispiel:

bash

curl -X POST https://ihreseite.de/wp-json/flowguard/v1/flows/123/run

Hinweise:

Gibt sofort mit Flow-Daten zurück
Die eigentliche Ausführung erfolgt auf dem externen Runner (Node.js-Server)
Aktualisiert Flow-Meta mit "running"-Status

Flow-Ergebnisse abrufen

Gibt Ausführungsergebnisse für einen Flow zurück.

Endpunkt:

GET /wp-json/flowguard/v1/flows/{id}/results

Parameter:

Parameter	Typ	Beschreibung
`id`	integer	Die Flow-Post-ID

Antwort:

json

{
  "id": 123,
  "title": "Login-Test-Flow",
  "last_run": {
    "timestamp": "2024-12-06T15:30:00",
    "status": "passed",
    "duration": 3450,
    "error": "",
    "results": [
      {
        "step": 1,
        "type": "navigate",
        "status": "passed",
        "duration": 1200,
        "error": ""
      },
      {
        "step": 2,
        "type": "click",
        "status": "passed",
        "duration": 350,
        "error": ""
      }
    ]
  }
}

Beispiel:

bash

curl https://ihreseite.de/wp-json/flowguard/v1/flows/123/results

Alle aktiven Flows ausführen

Führt alle Flows mit "active"-Status aus.

Endpunkt:

POST /wp-json/flowguard/v1/flows/run-all

Antwort:

json

{
  "success": true,
  "message": "Ausführung von 5 Flows gestartet.",
  "flows": [
    {
      "id": 123,
      "title": "Login-Test",
      "steps": [...],
      "settings": {...}
    },
    {
      "id": 124,
      "title": "Kontaktformular-Test",
      "steps": [...],
      "settings": {...}
    }
  ],
  "siteUrl": "https://ihreseite.de"
}

Beispiel:

bash

curl -X POST https://ihreseite.de/wp-json/flowguard/v1/flows/run-all

Flow-Statistiken abrufen

Gibt aggregierte Statistiken für alle Flows zurück.

Endpunkt:

GET /wp-json/flowguard/v1/flows/stats

Antwort:

json

{
  "success": true,
  "stats": {
    "total": 10,
    "active": 7,
    "inactive": 3,
    "passed": 5,
    "failed": 2,
    "pending": 3,
    "running": 0
  }
}

Beispiel:

bash

curl https://ihreseite.de/wp-json/flowguard/v1/flows/stats

Flow abbrechen

Bricht einen aktuell laufenden Flow ab.

Endpunkt:

POST /wp-json/flowguard/v1/flows/{id}/cancel

Parameter:

Parameter	Typ	Beschreibung
`id`	integer	Die Flow-Post-ID

Antwort:

json

{
  "success": true,
  "message": "Flow abgebrochen."
}

Berechtigungen: Erfordert manage_options-Berechtigung

Flow als Zeitüberschreitung markieren

Markiert einen laufenden Flow als Zeitüberschreitung (wird verwendet, wenn die Ausführung das konfigurierte Timeout überschreitet).

Endpunkt:

POST /wp-json/flowguard/v1/flows/{id}/timeout

Parameter:

Parameter	Typ	Beschreibung
`id`	integer	Die Flow-Post-ID

Antwort:

json

{
  "success": true,
  "message": "Flow als Zeitüberschreitung markiert."
}

Berechtigungen: Erfordert manage_options-Berechtigung

Einstellungs-Endpunkte

Einstellungen abrufen

Gibt alle Plugin-Einstellungen zurück.

Endpunkt:

GET /wp-json/flowguard/v1/settings

Antwort:

json

{
  "general": {
    "default_focus_mode": true
  },
  "test_mode": {
    "enabled": true,
    "email_strategy": "block",
    "test_email": "test@beispiel.de",
    "capture_error_screenshots": true
  },
  "execution": {
    "mode": "remote",
    "local_api_path": "",
    "local_port": 3000,
    "local_host": "localhost",
    "remote_url": ""
  }
}

Beispiel:

bash

curl https://ihreseite.de/wp-json/flowguard/v1/settings

Berechtigungen: Erfordert manage_options-Berechtigung

Einstellungen aktualisieren

Aktualisiert Plugin-Einstellungen.

Endpunkt:

PUT /wp-json/flowguard/v1/settings

Anfragekörper:

json

{
  "general": {
    "default_focus_mode": false
  },
  "execution": {
    "mode": "local",
    "local_api_path": "/var/www/flowguard-api",
    "local_port": 3000
  }
}

Antwort: Gibt das aktualisierte Einstellungs-Objekt zurück.

Beispiel:

bash

curl -X PUT https://ihreseite.de/wp-json/flowguard/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"general":{"default_focus_mode":true}}'

Berechtigungen: Erfordert manage_options-Berechtigung

Systemanforderungen prüfen

Prüft Systemanforderungen für den lokalen Ausführungsmodus.

Endpunkt:

GET /wp-json/flowguard/v1/system/requirements

Antwort:

json

{
  "requirements": [
    {
      "id": "nodejs",
      "name": "Node.js",
      "status": "installed",
      "version": "v20.10.0",
      "required": ">=18.0.0",
      "message": "Node.js v20.10.0 ist installiert"
    },
    {
      "id": "npm",
      "name": "npm",
      "status": "installed",
      "version": "10.2.3",
      "required": ">=8.0.0",
      "message": "npm 10.2.3 ist installiert"
    }
  ],
  "allMet": true,
  "canEnableLocal": true
}

Statuswerte:

installed - Anforderung erfüllt
not_installed - Anforderung nicht erfüllt
error - Fehler bei Anforderungsprüfung

Beispiel:

bash

curl https://ihreseite.de/wp-json/flowguard/v1/system/requirements

Berechtigungen: Erfordert manage_options-Berechtigung

Fehlerantworten

Standard-Fehlerformat

json

{
  "code": "rest_forbidden",
  "message": "Sie haben keine Berechtigung, Flows auszuführen.",
  "data": {
    "status": 403
  }
}

Häufige Fehlercodes

Code	Status	Beschreibung
`rest_forbidden`	403	Unzureichende Berechtigungen
`rest_no_route`	404	Endpunkt nicht gefunden
`rest_flow_not_found`	404	Flow-ID existiert nicht
`rest_flow_empty`	400	Flow hat keine Steps
`rest_invalid_param`	400	Ungültiger Parameterwert
`rest_cannot_update`	500	Aktualisierungsoperation fehlgeschlagen

Ratenbegrenzung

Die API begrenzt Anfragen zum Schutz vor Missbrauch:

Allgemeine API: 100 Anfragen pro 15 Minuten pro IP
Flow-Ausfuehrung: Begrenzt durch Queue-Concurrency (max 8 gleichzeitige Flows pro Worker)
Lizenz-Validierung: Brute-Force-Schutz mit automatischer IP-Sperre nach wiederholten Fehlversuchen
Monitoring-Checks: Konfigurierbare Intervalle (1-60 Minuten)

Bei Ueberschreitung des Limits wird eine 429 Too Many Requests Antwort zurueckgegeben.

Webhooks

Flowguard unterstützt Webhook-Benachrichtigungen für Monitoring-Alarme. Konfigurieren Sie diese unter Einstellungen > Benachrichtigungen:

Webhook-URL — Der Endpunkt, an den Alarme gesendet werden (z.B. Slack, Microsoft Teams oder eine benutzerdefinierte URL)
HTTP-Methode — POST oder GET
Ereignisse — Seite nicht erreichbar, Seite wiederhergestellt, Flow fehlgeschlagen

Webhook-Anfragen enthalten eine JSON-Payload mit Ereignisdetails (Seiten-URL, Zeitstempel, Fehlerinformationen, Ausfallzeit).

Code-Beispiele

JavaScript (Fetch API)

javascript

// Alle Flows abrufen
fetch('/wp-json/wp/v2/flowguard-flows')
  .then(response => response.json())
  .then(flows => console.log(flows));

// Flow ausführen
fetch('/wp-json/flowguard/v1/flows/123/run', {
  method: 'POST',
  headers: {
    'X-WP-Nonce': wpApiSettings.nonce
  }
})
  .then(response => response.json())
  .then(result => console.log(result));

PHP

php

// Flow-Ergebnisse abrufen
$response = wp_remote_get(
  home_url('/wp-json/flowguard/v1/flows/123/results')
);
$results = json_decode(wp_remote_retrieve_body($response));

// Alle aktiven Flows ausführen
$response = wp_remote_post(
  home_url('/wp-json/flowguard/v1/flows/run-all')
);

Python

python

import requests
from requests.auth import HTTPBasicAuth

# Konfiguration
site_url = 'https://ihreseite.de'
username = 'admin'
app_password = 'xxxx xxxx xxxx xxxx xxxx xxxx'

# Flow-Statistiken abrufen
response = requests.get(
    f'{site_url}/wp-json/flowguard/v1/flows/stats',
    auth=HTTPBasicAuth(username, app_password)
)
stats = response.json()
print(stats)

# Flow ausführen
response = requests.post(
    f'{site_url}/wp-json/flowguard/v1/flows/123/run',
    auth=HTTPBasicAuth(username, app_password)
)
result = response.json()
print(result)

cURL

bash

# Alle Flows abrufen
curl https://ihreseite.de/wp-json/wp/v2/flowguard-flows

# Flow mit Authentifizierung ausführen
curl -X POST \
  -u 'benutzername:xxxx xxxx xxxx xxxx xxxx xxxx' \
  https://ihreseite.de/wp-json/flowguard/v1/flows/123/run

# Statistiken abrufen
curl https://ihreseite.de/wp-json/flowguard/v1/flows/stats

Best Practices

Geeignete HTTP-Methoden verwenden

GET zum Lesen von Daten
POST zum Erstellen und Ausführen
PUT oder PATCH zum Aktualisieren
DELETE zum Entfernen

Fehler behandeln

Prüfen Sie immer den Antwortstatus und behandeln Sie Fehler:

javascript

fetch('/wp-json/flowguard/v1/flows/123/run', {
  method: 'POST'
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Fehler:', error));

Berechtigungen respektieren

Stellen Sie sicher, dass Ihr Benutzerkonto die nötigen Berechtigungen hat, bevor Sie Anfragen stellen.

HTTPS verwenden

Verwenden Sie immer HTTPS in der Produktion, um Authentifizierungsdaten zu schützen.

Geplante Erweiterungen

Batch-Operationen
Echtzeit-Ausführungs-Streaming
Flow-Versionierungs-Endpunkte
Import/Export-Endpunkte

Support

Bei API-Problemen:

Prüfen Sie, ob die WordPress REST API aktiviert ist
Überprüfen Sie, ob die Authentifizierung funktioniert
Prüfen Sie Fehlerantworten auf Details
Überprüfen Sie WordPress- und Flowguard-Protokolle
Testen Sie mit einem REST-Client (Postman, Insomnia)

REST API ​

Basis-URL ​

Authentifizierung ​

Cookie-Authentifizierung ​

Anwendungspasswörter ​

Berechtigungen ​

Flow-Endpunkte ​

Einstellungs-Endpunkte ​

Flow-Endpunkte ​

Flows auflisten ​

Einzelnen Flow abrufen ​

Flow erstellen ​

Flow aktualisieren ​

Flow löschen ​

Flow-Ausführungs-Endpunkte ​

Einzelnen Flow ausführen ​

Flow-Ergebnisse abrufen ​

Alle aktiven Flows ausführen ​

Flow-Statistiken abrufen ​

Flow abbrechen ​

Flow als Zeitüberschreitung markieren ​

Einstellungs-Endpunkte ​

Einstellungen abrufen ​

Einstellungen aktualisieren ​

Systemanforderungen prüfen ​

Fehlerantworten ​

Standard-Fehlerformat ​

Häufige Fehlercodes ​

Ratenbegrenzung ​

Webhooks ​

Code-Beispiele ​

JavaScript (Fetch API) ​

PHP ​

Python ​

cURL ​

Best Practices ​

Geeignete HTTP-Methoden verwenden ​

Fehler behandeln ​

Berechtigungen respektieren ​

HTTPS verwenden ​

Verwandte Dokumentation ​

Geplante Erweiterungen ​

Support ​

REST API

Basis-URL

Authentifizierung

Cookie-Authentifizierung

Anwendungspasswörter

Berechtigungen

Flow-Endpunkte

Einstellungs-Endpunkte

Flow-Endpunkte

Flows auflisten

Einzelnen Flow abrufen

Flow erstellen

Flow aktualisieren

Flow löschen

Flow-Ausführungs-Endpunkte

Einzelnen Flow ausführen

Flow-Ergebnisse abrufen

Alle aktiven Flows ausführen

Flow-Statistiken abrufen

Flow abbrechen

Flow als Zeitüberschreitung markieren

Einstellungs-Endpunkte

Einstellungen abrufen

Einstellungen aktualisieren

Systemanforderungen prüfen

Fehlerantworten

Standard-Fehlerformat

Häufige Fehlercodes

Ratenbegrenzung

Webhooks

Code-Beispiele

JavaScript (Fetch API)

PHP

Python

cURL

Best Practices

Geeignete HTTP-Methoden verwenden

Fehler behandeln

Berechtigungen respektieren

HTTPS verwenden

Verwandte Dokumentation

Geplante Erweiterungen

Support