Ein Suchbildschirm braucht mehr als Ergebnisse oder Fehler

Ein Storyboard, keine Dienststatusanzeige

Dies sind vorgeschlagene Zustände für eine von Entwicklern betriebene Wander-App. Es handelt sich weder um aufgezeichnete API-Antworten noch um vorgeführte laufende Bildschirme oder einen Nachweis verfügbarer Offline-Karten-Datensätze. Die wandernde Person nutzt Ihre App; der API-Kontobetreiber verwaltet Dienstschlüssel und Guthaben. Geben Sie beiden nur Informationen, mit denen sie etwas anfangen können.

Erklären Sie vor der ersten Suche, dass die Funktion historische Diskussionen liest. Ein Vorschlag wie offline maps kann den Einstieg erleichtern; zeigen Sie aber keine erfundenen Empfehlungen, als sei die Suche bereits ausgeführt worden. Behalten Sie eine ausdrückliche Suchaktion bei, damit Tippen und das Erkunden des Formulars keine kostenpflichtige Anfrage auslösen müssen.

Laden: die Frage sichtbar halten

Erhalten Sie während einer ausstehenden Anfrage die abgesendete Abfrage und die gewählten Filter. Markieren Sie den Ergebnisbereich als ladend, verhindern Sie doppelte Absendungen derselben Aktion und ergänzen Sie Animationen um eine zugängliche Textkennzeichnung. Eine Verzögerung allein weist weder einen Dienstausfall noch dessen Ursache nach.

Wenn die Person die Abfrage ändert, bevor eine frühere Antwort eintrifft, ordnen Sie jede Antwort ihrer abgesendeten Eingabe zu. Platzieren Sie Ergebnisse zur alten Frage nicht stillschweigend unter der neuen. Das ist eine zu testende Implementierungsentscheidung der App, kein vom Archiv bereitgestelltes Reihenfolge- oder Abbruchverhalten.

Erfolg kann Datensätze enthalten oder leer bleiben

Zeigen Sie bei zurückgegebenen Datensätzen nur vorhandene Felder und kennzeichnen Sie das Material als historisch. Ein Kommentar muss keinen Titel haben; ein fehlendes Datum bleibt unbekannt. Beschreiben Sie die sichtbare Seite, statt bei pagination.relation gte oder unknown eine exakte Trefferzahl anzukündigen.

Eine erfolgreiche leere Antwort ist ein eigener Zustand. Eine mögliche Meldung lautet: Für diese Anfrage wurden keine Datensätze zurückgegeben. Bieten Sie eine bewusste Änderung von Formulierung oder Filtern an und halten Sie die bisherige Eingabe verfügbar. Behaupten Sie nicht, eine solche Diskussion existiere nirgends. Auch ein erfolgreicher leerer Abruf kostet einen Credit.

400, 401 und 402 betreffen unterschiedliche Verantwortliche

HTTP 400 kennzeichnet ungültige Anfrageeingaben. Prüfen Sie das tatsächliche Parameterproblem, etwa einen nicht unterstützten Parameter, eine Seite außerhalb der Grenzen oder ein Datum, das nicht YYYY-MM-DD entspricht. Erklären Sie Wandernden gegebenenfalls ein korrigierbares Feld; Fehler im Backendvertrag gehören in die Betreiberdiagnose.

HTTP 401 bedeutet, dass der API-Dienstschlüssel fehlt oder ungültig ist. Daraus folgt nicht, dass die App-Sitzung der wandernden Person abgelaufen ist; für diese API-Schlüssel ist kein zeitgesteuerter Ablaufmechanismus dokumentiert. Der Betreiber prüft den gespeicherten domainspezifischen Schlüssel und eine mögliche kürzliche Neugenerierung. Fordern Sie Wandernde weder zur Schlüsseleingabe noch zur Anmeldung am Dienstkonto auf.

HTTP 402 bedeutet unzureichendes Guthaben im Dienstkonto. Eine Meldung für Wandernde könnte lauten: Die Diskussionssuche ist vorübergehend pausiert. Der Betreiber kann sich unter Schlüssel und Guthaben anmelden und den Stand prüfen. Eine neue Anfrage ist eine eigene Aktion, nachdem die Ursache behoben wurde; bloßes Wiederholen der alten Anfrage ist keine Lösung.

429, vorgelagerte Fehler und ungewisse Zustellung

HTTP 429 bedeutet, dass eine Ratenbegrenzung erreicht wurde. Beachten Sie Retry-After, reduzieren Sie wiederholte Absendungen und lassen Sie die Person zu einem passenden Zeitpunkt erneut versuchen. Die Begrenzung kann ein gemeinsam genutztes Backend oder Konto betreffen; machen Sie nicht einzelne Wandernde dafür verantwortlich. Vermeiden Sie unbegrenzte automatische Wiederholungsschleifen.

Das Gateway meldet Fehler des vorgelagerten Systems als HTTP 502. Erhalten Sie die Abfrage und bieten Sie eine ausdrückliche Wiederholungsoption an, ohne den Erfolg des nächsten Versuchs zu versprechen. Bei einer fehlgeschlagenen Anfrage im vorgelagerten System wird reserviertes Guthaben erstattet; die Antwort kann auch eine noch ausstehende Abstimmung melden. Verliert Ihre App die Antwort vollständig, ist das endgültige Abrechnungsergebnis ungewiss: Der Server könnte erfolgreich abgeschlossen haben.

Die öffentliche Route /v1/status liefert einen statischen Hinweis zum Dienstumfang und zeigt, dass ihr HTTP-Handler antwortet. Sie testet weder die Archivsuche noch bescheinigt sie die Funktionsfähigkeit vorgelagerter Systeme. Treffen Sie Betriebsentscheidungen anhand des tatsächlichen Anfrageergebnisses. Den vollständigen Ablauf finden Sie im App-Rundgang, weitere Umsetzungsentscheidungen in der Praxisnotiz zu Lade-, Leer- und Fehlerzuständen.