Una schermata di ricerca richiede più di risultati o errore

Uno storyboard, non un indicatore dello stato del servizio

Questi sono stati proposti per un’app escursionistica gestita dallo sviluppatore. Non sono risposte API registrate, dimostrazioni di schermate funzionanti o prove della disponibilità di record sulle mappe offline. L’escursionista usa la tua app; il gestore dell’account API amministra credenziale e crediti del servizio. Dai a ciascuno le informazioni su cui può intervenire.

Prima della prima ricerca, spiega che la funzione legge discussioni storiche. Una query suggerita come offline maps può facilitare l’inizio, ma non mostrare raccomandazioni inventate come se la ricerca fosse già avvenuta. Mantieni un’azione Cerca esplicita, così digitare ed esplorare il modulo non deve attivare richieste a pagamento.

Durante il caricamento, lasciare visibile la domanda

Finché la richiesta è in corso, conserva query inviata e filtri scelti. Contrassegna l’area dei risultati come in caricamento, evita invii duplicati per quell’azione e affianca alle animazioni un’etichetta testuale accessibile. Un ritardo, da solo, non identifica un’interruzione del servizio o la sua causa.

Se la persona cambia query prima che arrivi una risposta precedente, associa ogni risposta all’input inviato. Non collocare silenziosamente risultati della vecchia domanda sotto quella nuova. È una scelta implementativa dell’app da verificare, non un comportamento di ordinamento o annullamento fornito dall’API dell’archivio.

Un successo può contenere record oppure nulla

Quando arrivano record, mostra solo i campi disponibili e identifica il materiale come storico. Un commento può non avere un titolo e una data mancante deve restare sconosciuta. Descrivi la pagina visibile, invece di annunciare un numero esatto di corrispondenze quando pagination.relation è gte o unknown.

Una risposta vuota riuscita è un esito distinto. Un possibile messaggio è: Nessun record è stato restituito per questa richiesta. Offri una modifica intenzionale della formulazione o dei filtri, mantenendo l’input precedente disponibile. Non affermare che non esista da nessuna parte una discussione simile. Anche un recupero vuoto riuscito costa un credito.

400, 401 e 402 hanno responsabili diversi

HTTP 400 indica input della richiesta non valido. Controlla il problema concreto: per esempio un parametro non supportato, una pagina fuori intervallo o una data non in formato YYYY-MM-DD. Quando pertinente, spiega all’escursionista il campo correggibile; gli errori di contratto del backend vanno nella diagnostica del gestore.

HTTP 401 significa che la chiave API del servizio è assente o non valida. Non dimostra che la sessione dell’app dell’escursionista sia scaduta, e queste chiavi API non hanno un meccanismo documentato di scadenza temporizzata. Il gestore controlla la chiave salvata per il dominio e un’eventuale rigenerazione recente. Non chiedere all’escursionista di fornire una chiave o accedere all’account del servizio.

HTTP 402 significa crediti insufficienti nell’account del servizio. Un messaggio rivolto all’escursionista potrebbe dire che la ricerca di discussioni è temporaneamente sospesa. Il gestore può accedere a Chiave e crediti e controllare il saldo. Una nuova richiesta è un’azione separata, successiva alla risoluzione della causa; ripetere semplicemente quella vecchia non è un rimedio.

429, problemi a monte e consegna incerta

HTTP 429 significa che è stato raggiunto un limite di frequenza. Rispetta Retry-After, riduci invii ripetuti e lascia riprovare quando opportuno. Il limite può riguardare un backend o account condiviso, quindi evita di attribuire la colpa a un singolo escursionista. Non creare un ciclo illimitato di tentativi automatici.

Il gateway segnala i problemi del sistema a monte con HTTP 502. Conserva la query e mostra una possibilità esplicita di riprovare, senza promettere il successo del tentativo seguente. Il credito riservato viene rimborsato se la richiesta a monte fallisce; la risposta può anche indicare una riconciliazione in sospeso. Se l’app perde interamente la risposta, l’esito finale dell’addebito è incerto: il server potrebbe aver concluso con successo.

La rotta pubblica /v1/status fornisce una dichiarazione statica sul perimetro del servizio e mostra che il suo gestore HTTP risponde. Non prova la ricerca nell’archivio né certifica lo stato dei sistemi a monte. Basa le decisioni operative sull’esito reale della richiesta. Torna alla Guida all’app per lo storyboard completo o alla nota sulle schermate di caricamento, vuote e di errore per le scelte implementative.