Eine angenommene Anfrage braucht ein sichtbares Ergebnis

Eine Erfolgsmeldung im Portal sollte den Zustand belegen, auf den sich der Nutzer verlässt. Wer einen fertigen Bericht erwartet, braucht einen abrufbaren Bericht. Die Annahme eines Erstellungsauftrags ist dafür ein Zwischenschritt. Diese Unterscheidung gehört zur Produktentscheidung über die Rückmeldung.

MDN beschreibt HTTP 202 als Annahme einer noch nicht abgeschlossenen Verarbeitung. Die Arbeit kann später scheitern. Microsoft zeigt für solche asynchronen Abläufe eine getrennte Statusabfrage. Der HTTP-Code der ersten Antwort beendet deshalb nicht die Frage, was das Portal anschließend anzeigen soll.

Dieselbe Annahme, zwei Oberflächen

In unserem fiktiven Portal wird der Berichtsauftrag J-73 angenommen. Die Vorlage ist zunächst verfügbar, wird aber vor der Verarbeitung entfernt. Der folgende Vergleich beschreibt zwei mögliche Oberflächen, keinen durchgeführten Nutzertest.

Beide Oberflächen könnten dieselbe Annahmeantwort erhalten haben. Trotzdem geben sie unterschiedliche Auskünfte. In A kann die technische Annahme eine fachlich unerfüllte Erwartung verdecken. B hält den Vorgang sichtbar, bis sein Ausgang feststeht.

Eine erfolgreiche Statusabfrage kann einen Fehler zeigen

Unsere Beispiel-API liefert für das erfolgreiche Lesen der Statusressource HTTP 200 mit folgendem Inhalt:

{"jobId":"J-73","status":"failed","error":{"code":"template-not-found"}}

Der Abruf hat funktioniert; die Berichtserstellung ist gescheitert. Feldnamen und Antwortgestaltung sind eigene Beispielregeln, keine Vorgabe für jede API. Eine Auswertung, die nur erfolgreiche HTTP-Aufrufe zählt, könnte diesen Vorgang übersehen. Anfrageannahmen, erledigte Berichte und fehlgeschlagene Arbeiten beantworten verschiedene Fragen.

Ist die Statusabfrage selbst nicht erreichbar, bleibt der aktuelle Arbeitszustand unbekannt. Das Portal sollte daraus keinen fertigen Bericht und keinen sicher gescheiterten Auftrag ableiten. Auch ein erneuter Klick muss zum vorhandenen Vorgang passen, damit eine unklare Lage nicht durch zusätzliche Aufträge verschärft wird.

Wann die Annahme als Ergebnis ausreicht

Eine reine Einlieferungsfunktion kann mit der dauerhaften Aufnahme ihre vereinbarte Aufgabe erfüllen. Dann ist eine als Annahme beschriftete Bestätigung passend. Ebenso braucht ein synchron vollständig erledigter Vorgang keinen zusätzlichen Abfragezyklus nur aus Prinzip.

Für das Berichtsportal gilt jedoch ein anderes Ziel: Der Nutzer möchte die Datei erhalten. Die Bewertung der Integration muss deshalb bis zu diesem Ergebnis und einem nachvollziehbaren Fehlerweg reichen. Eine schnelle erste Antwort ist dann eine eigene Eigenschaft, kein Nachweis eines verfügbaren Berichts.

Quellen

• MDN: 202 Accepted

• Microsoft: Asynchronous Request-Reply pattern