Lang laufende Operationen: 202 Accepted und eine Statusressource

Worum es geht

RFC 9110 (zitiert) definiert 202 (Accepted) als bewusst unverbindlich: Die Anfrage wurde zur Verarbeitung angenommen, die Verarbeitung ist aber noch nicht abgeschlossen, sie kann später noch abgelehnt werden, und HTTP hat keinen Mechanismus, um nachträglich einen Statuscode einer asynchronen Operation zuzustellen. Die mit einem 202 gesendete Repräsentation sollte den aktuellen Status der Anfrage beschreiben und auf einen Statusmonitor verweisen (oder ihn einbetten). Googles AIP-151 (zitiert) macht diesen Monitor zu einer vollwertigen Ressource: Methoden, die erheblich Zeit beanspruchen können, geben eine Operation mit einem Namen, einem done-Flag, metadata für Fortschritt und Teilfehlschläge sowie nach Abschluss entweder error oder response zurück. Als Faustregel gilt, dass Arbeit über rund 10 Sekunden das Muster rechtfertigt und dass Operationen verfallen dürfen, wobei 30 Tage vorgeschlagen werden.

Warum es wichtig ist

Eine Verbindung minutenlang zu blockieren scheitert auf jeder Ebene: Proxys kappen inaktive Verbindungen, Clients laufen in ein Timeout und wiederholen die Anfrage, und ein wiederholter, nicht idempotenter Job läuft zweimal. Eine explizite Operations-Ressource erlaubt es dem Client, die Verbindung zu trennen, abzufragen und sich nach einem eigenen Neustart zu erholen, und gibt dem Server eine einzige Stelle, um das Ergebnis festzuhalten.

So wird es angewendet

• 202 Accepted mit einem Location-Header (oder einem Link im Body) zu /operations/{id} zurückgeben und die Repräsentation der Operation im Body mitliefern, damit der Client keine sofortige zweite Anfrage braucht.
• Die Operation mit done, metadata (Fortschritt, Zähler, nicht fatale Fehler) und nach Abschluss genau einem von error oder response modellieren; dieselbe Fehlerform wie bei synchronen Fehlschlägen verwenden.
• Einen vom Client mitgelieferten Idempotenzschlüssel bei der Start-Anfrage akzeptieren, damit eine Wiederholung nach einem verlorenen 202 dieselbe Operation zurückgibt, statt eine zweite zu starten.
• Abfragen mit Retry-After-Hinweisen unterstützen; für Clients, die einen empfangen können, einen Webhook anbieten, Polling aber als Fallback behalten.
• Verfall dokumentieren: wie lange das Ergebnis abrufbar bleibt und was ein GET auf eine verfallene Operation zurückgibt.
• Bei asynchron erzeugten Ressourcen List und Get die Ressource mit einem Zustand anzeigen lassen, der sie als noch nicht nutzbar kennzeichnet (AIP-151).
• Entscheiden, wie parallele Operationen auf einer Ressource sich verhalten: sie in eine Warteschlange stellen oder mit einem Konfliktfehler ablehnen, der die laufende Operation benennt.

Stolpersteine

202 zurückgeben und dann trotzdem synchron verarbeiten. Den Ergebnistyp einer bestehenden Operation ändern, was AIP-151 als breaking Change auflistet. 200 mit einem «pending»-Body verwenden, wodurch Caches und Clients den Job als abgeschlossen behandeln. Operationsaufzeichnungen bei einem Neustart verlieren, sodass der Client das Ergebnis nie erfahren kann. Abfrage-Endpunkte ohne Ratenbegrenzung.

Synchron antworten, wenn die Arbeit schnell ist

Ist die Latenz bimodal, pro Anfrage entscheiden, nicht pro Operationstyp. Den Job für eine begrenzte Zeit laufen lassen und, falls er abschliesst, mit 200 oder 201 samt Ergebnis antworten; andernfalls mit 202 und der Operations-Ressource. RFC 7240 gibt dem Client ein Mitspracherecht: Prefer: wait=N begrenzt, wie lange er warten wird, Prefer: respond-async fordert direkt den 202-Pfad an, und der Server meldet in Preference-Applied, was er befolgt hat. Beide Antwortformen für die Operation dokumentieren und sie durch den Wait-Helfer des SDK normalisieren lassen, damit Aufrufer einen einzigen Ergebnistyp sehen. Das immer-202-Design für Arbeit reservieren, die stets lange dauert.