01
Synchronous HTTP request
Eine Anfrage geht rein und die fertige Antwort kommt in derselben HTTP-Verbindung zurück.
Geeignet für
Direkte UI-Aktionen, kurze Texte, geringe Latenz
Demo
Modi, Einstellungen und API-Transport in einem Bild.
Die Demo zeigt zuerst den fachlichen Kern der API: `mode`, `rewriteScope` und `qualityHints`. Danach folgen die vier Transportmuster für unterschiedliche Integrationslandschaften.
Interaktives Beispiel
Request und Response ändern sich mit jeder Einstellung.
Hier lässt sich direkt nachvollziehen, wie Einfache Sprache, Leichte Sprache, vollständige oder verdichtete Antworten und optionale Qualitätshinweise zusammenwirken.
Eingabe
Ausgangstext und Einstellungen
290 / 1.000 Zeichen
Modus
Ausgabetiefe
Request
{
"text": "Um die Bearbeitung zu beschleunigen, müssen Nutzerinnen und Nutzer nach erfolgreicher Anmeldung zunächst ihre persönlichen Angaben prüfen, gegebenenfalls aktualisieren und den Vorgang anschließend digital bestätigen. Nach dem Absenden erhalten sie eine Nachricht mit den nächsten Schritten.",
"mode": "einfache-sprache",
"settings": {
"rewriteScope": "complete",
"qualityHints": false
}
}Ausgabe
Einfache Sprache
Abgeschlossen800 ms
Nach dem Absenden erscheint hier die gestreamte Übersetzung.
Response
{
"requestId": "simple8_case_01",
"cacheStatus": "hit",
"durationMs": 800,
"mode": "einfache-sprache",
"settings": {
"rewriteScope": "complete",
"qualityHints": false
},
"output": {
"text": "Melden Sie sich zuerst an. Prüfen Sie dann Ihre persönlichen Angaben. Ändern Sie falsche Angaben direkt online. Bestätigen Sie den Vorgang danach digital. Danach erhalten Sie eine Nachricht mit den nächsten Schritten."
}
}API-Architekturen
Alle vier Muster lösen denselben fachlichen Auftrag, aber mit anderer Transportlogik.
Die Wahl hängt davon ab, ob das Ergebnis sofort benötigt wird, ob Fortschritt sichtbar sein soll und ob das aufrufende System aktiv warten, pollen oder per Event benachrichtigt werden kann.
02
One request + streaming response
Eine Anfrage startet die Verarbeitung, die Antwort kommt schrittweise als Stream zurück.
Geeignet für
Längere Inhalte, progressive UI, sichtbarer Verarbeitungsfortschritt
03
Async job + polling
Der erste Request erzeugt einen Job, danach fragt der Client den Status wiederholt ab.
Geeignet für
Batch-Verarbeitung, Backends, längere Jobs ohne dauerhafte offene Verbindung
04
Async job + webhook
Der erste Request erzeugt einen Job, die Fertigmeldung kommt später aktiv per Webhook zurück.
Geeignet für
CMS-Workflows, Ereignisarchitektur, zuverlässige System-zu-System-Integration
Die vier Muster
Konzept, technische Umsetzung und konkrete Beispiele je Architektur.
01
Synchronous HTTP request
Eine Anfrage geht rein und die fertige Antwort kommt in derselben HTTP-Verbindung zurück.
Konzept
Das aufrufende System sendet einen Request und wartet aktiv auf das Ergebnis. `mode` und `settings` werden im selben Request übergeben und bestimmen direkt die Form der Antwort.
Zitatbeispiel
“Wir senden einzelne Formulartexte direkt an simple8 und bekommen sofort die passende Sprachfassung für den gewählten Modus zurück.”
Technisch
- Typisch ist ein `POST /api/translate` mit Text, Sprachmodus und Einstellungen.
- Die API liefert bei Erfolg direkt `200 OK` mit dem vereinfachten Text zurück.
- Wenn `qualityHints=false`, enthält die Antwort keine zusätzlichen Qualitätshinweise.
Beispielablauf
POST /api/translate
{
"text": "Für die Beantragung des Personalausweises bringen Sie bitte Ihren alten Ausweis oder Reisepass sowie ein aktuelles Lichtbild mit.",
"mode": "einfache-sprache",
"settings": {
"rewriteScope": "complete",
"qualityHints": false
}
}
200 OK
{
"requestId": "req_sync_001",
"cacheStatus": "miss",
"durationMs": 980,
"mode": "einfache-sprache",
"settings": {
"rewriteScope": "complete",
"qualityHints": false
},
"output": {
"text": "Wenn Sie einen Personalausweis beantragen, bringen Sie bitte Ihren alten Ausweis oder Reisepass und ein aktuelles Foto mit."
}
}02
One request + streaming response
Eine Anfrage startet die Verarbeitung, die Antwort kommt schrittweise als Stream zurück.
Konzept
Der Client startet nur einen Request, bleibt aber nicht bis zum Schluss blind. Statt einer einzigen Endantwort erhält er laufend Status- oder Inhalts-Updates über dieselbe Verbindung.
Zitatbeispiel
“Unsere Redaktion soll sehen, welche Fassung gerade entsteht, und bei Bedarf sofort die Qualitätshinweise mitbekommen.”
Technisch
- Der Request enthält dieselben fachlichen Optionen wie im synchronen Muster: `mode`, `rewriteScope` und optional `qualityHints`.
- Der Client verarbeitet Events wie `status`, `delta` und `completed`, ohne neue Requests abzusetzen.
- Wenn `qualityHints` aktiv ist, kann die finale `completed`-Nachricht zusätzliche Qualitätshinweise enthalten.
Beispielablauf
POST /api/translate/stream
{
"text": "Nach der Beantragung des Personalausweises erhalten Sie ein Schreiben, sobald das Dokument in der Behörde zur Abholung bereitliegt.",
"mode": "leichte-sprache",
"settings": {
"rewriteScope": "complete",
"qualityHints": true
}
}
event: status
data: {"state":"processing","mode":"leichte-sprache"}
event: delta
data: {"chunk":"Nach dem Antrag bekommen Sie ein Schreiben.\n"}
event: delta
data: {"chunk":"Dann wissen Sie: Ihr Ausweis liegt bereit.\n"}
event: completed
data: {
"requestId": "req_stream_001",
"cacheStatus": "miss",
"mode": "leichte-sprache",
"settings": {
"rewriteScope": "complete",
"qualityHints": true
},
"output": {
"text": "Nach dem Antrag bekommen Sie ein Schreiben.\nDann wissen Sie: Ihr Ausweis liegt bereit.",
"qualityHints": [
"Die Ausgabe nutzt sehr kurze Sätze mit klarer Reihenfolge."
]
}
}03
Async job + polling
Der erste Request erzeugt einen Job, danach fragt der Client den Status wiederholt ab.
Konzept
Die eigentliche Verarbeitung wird vom ersten HTTP-Aufruf entkoppelt. Das aufrufende System erhält sofort eine Job-ID und kontrolliert später selbst, wann es den Status erneut abfragt.
Zitatbeispiel
“Unser Backend stößt viele Texte gesammelt an und fragt später gezielt ab, welche Modus-Variante fertig ist.”
Technisch
- Ein `POST` erzeugt einen Job und speichert die gewählte Kombination aus Modus und Einstellungen mit.
- Der Client fragt `GET /api/jobs/{id}` in Intervallen ab, bis `queued`, `running`, `completed` oder `failed` gemeldet wird.
- Polling eignet sich gut, wenn verdichtete oder analysierte Fassungen in größere Batch-Flows eingeordnet werden.
Beispielablauf
POST /api/jobs
{
"text": "Für die Beantragung des Personalausweises müssen Sie persönlich im Bürgeramt vorsprechen. Minderjährige brauchen die Zustimmung der Sorgeberechtigten.",
"mode": "einfache-sprache",
"settings": {
"rewriteScope": "condensed",
"qualityHints": true
}
}
202 Accepted
{
"jobId": "job_poll_001",
"status": "queued"
}
GET /api/jobs/job_poll_001
{
"jobId": "job_poll_001",
"status": "completed",
"mode": "einfache-sprache",
"settings": {
"rewriteScope": "condensed",
"qualityHints": true
},
"output": {
"text": "Für den Personalausweis müssen Sie persönlich ins Bürgeramt gehen.",
"qualityHints": [
"Die Ausgabe konzentriert sich auf die wichtigsten Aussagen und lässt Nebendetails weg."
]
}
}04
Async job + webhook
Der erste Request erzeugt einen Job, die Fertigmeldung kommt später aktiv per Webhook zurück.
Konzept
Auch hier wird die Verarbeitung asynchron gestartet. Anders als beim Polling fragt der Client den Status nicht wiederholt ab, sondern wird aktiv benachrichtigt, sobald Ergebnis oder Fehler vorliegen.
Zitatbeispiel
“Unser CMS entscheidet je Inhalt, ob Einfache Sprache oder Leichte Sprache gebraucht wird, und speichert die fertige Fassung erst nach dem Webhook.”
Technisch
- Der Start-Request übermittelt neben den Fachdaten auch Modus, Einstellungen und `webhookUrl`.
- Nach Abschluss sendet die API ein signiertes `POST`-Event an das Zielsystem.
- Webhook-Flows sind besonders nützlich, wenn unterschiedliche Ausgabemodi in Publishing- oder Freigabeprozesse eingespeist werden.
Beispielablauf
POST /api/jobs
{
"text": "Wenn Sie Ihren Personalausweis beantragen, können Gebühren anfallen. Bitte bringen Sie die erforderlichen Unterlagen vollständig zum Termin mit.",
"mode": "leichte-sprache",
"settings": {
"rewriteScope": "condensed",
"qualityHints": false
},
"webhookUrl": "https://cms.example.com/webhooks/simple8"
}
202 Accepted
{
"jobId": "job_hook_001",
"status": "queued"
}
POST https://cms.example.com/webhooks/simple8
simple8-signature: sha256=...
{
"event": "job.completed",
"jobId": "job_hook_001",
"mode": "leichte-sprache",
"settings": {
"rewriteScope": "condensed",
"qualityHints": false
},
"output": {
"text": "Für den Personalausweis können Gebühren anfallen.\nBringen Sie bitte alle nötigen Unterlagen mit."
}
}