En API uden resultat og en API med fejl kræver to forskellige håndteringer. Et vellykket søgning kan returnere ingen steder indenfor det anmodede område. En netværksfejl, en nået grænse eller en utilgængelig kilde forhindrer derimod at konkludere på baggrund af søgningen.
For ROOTE, kontroller HTTP-svaret, derefter forretningsstatus, den forventede samling og dækningen. Denne tilgang undgår at vise «ingen toiletter», når et tjenestekald er mislykket, eller «intet stop» efter en overskredet ventetid.
Læs de tre niveauer af et svar
| Niveau | At kontrollere | Mulig konklusion |
|---|---|---|
| Transport | Forbindelse, timeout og HTTP-status | Gennemførtes forespørgslen? |
| Kontrakt | Gyldigt JSON, version og forventede felter | Er svaret anvendeligt? |
| Forretningsresultat | status, samlinger, dækning, advarsler og meta | Hvad ved vi indenfor det anmodede område? |
En HTTP 200-kode er ikke nok til at validere en søgning. Svaret kan angive delvis udførelse eller en error-status. Omvendt er 404 på en rute ikke en normal måde at udtrykke en tom samling på: tjek URL og kontrakt.
Forstå success, empty, partial og error
| Status | Anbefalet behandling |
|---|---|
| success | Vis enheder efter validering og behold begrænsninger |
| empty | Angiv, at der ikke blev returneret noget resultat for denne søgning |
| partial | Vis brugbare oplysninger med deres advarsler |
| error | Præsenter søgningen som utilgængelig; konkluder ikke, at der ikke findes steder |
Fravær af resultat gælder for en forespørgsel og kendte kilder. Det beviser ikke, at ingen tjeneste fysisk eksisterer. En ikke-udtømmende dækning, et restriktivt filter eller en anvendt grænse kan reducere resultaterne.
Et beslutningstræ til din brugerflade
1. La requête a-t-elle abouti ?
Non → indisponibilité réseau ou délai dépassé.
2. Le statut HTTP est-il acceptable selon le contrat ?
Non → traiter le code et le message d'erreur.
3. Le JSON respecte-t-il le schéma attendu ?
Non → réponse inexploitable, jamais "aucun résultat".
4. Le statut métier est-il error ?
Oui → recherche indisponible.
5. Le statut est-il partial ou la couverture limitée ?
Oui → résultats utilisables + avertissement.
6. La collection attendue est-elle vide ?
Oui → aucun résultat retourné dans ce périmètre.
Non → afficher les résultats et leurs limites.Tjek parametre i korrekt rækkefølge
Kontroller først breddegrad og længdegrad, deres rækkefølge og den opnåede by. Tjek derefter radiusenhed og filterets vokabular. API Services bruger types=toilets; et kort-URL bruger modes=toilets. Disse parametre tilhører forskellige kontrakter.
Udvid derefter kun én dimension ad gangen: øg radius inden for ruddets begrænsninger eller fjern et filter for en eksplicit test. Gem sporet af den oprindelige forespørgsel. Hvis du udvider automatisk, angiv den nye grænse til brugeren.
Opbyg en API-søgning rundt om GPS-koordinater
Håndter en utilgængelig kilde uden at miste de andre
Et delvist svar kan indeholde steder fra kilder, der har svaret, mens en anden fejlede. Behold disse resultater, deres tilskrivninger og den relevante advarsel. Præsenter ikke listen som udtømmende, og erstat ikke manglende felter med vildledende standardværdier.
Ældre information gemt i cache kan også være nyttig, hvis din politik tillader dette fallback. Det skal forblive markeret som gammelt. Modtagelsestidspunktet for din forespørgsel forynger ikke den oprindelige observation.
Tilpas beskeder og genoptagelser
| Situation | Besked tilpasning til din brugerflade | Handling |
|---|---|---|
| empty | Ingen resultater indenfor dette område med disse filtre | Ændr området eller filtrene |
| partial | Nogle resultater er tilgængelige; søgningen er ufuldstændig | Vis resultater og advarsel |
| Valideringsfejl | Søgningen indeholder en ugyldig parameter | Korriger forespørgslen |
| Godkendelse eller rettigheder | Denne adgang tillader ikke denne søgning | Tjek konto eller token |
| Begrænsning eller utilgængelighed | Søgningen er midlertidigt utilgængelig | Følg genoptagelsesvejledninger |
For en 429, se tjenestens anvisninger og eventuelt Retry-After. En 400-fejl kræver korrektion af argumenter; gentagelse af samme forespørgsel løser det ikke. Forvandl ikke en 401 til et anonymt kald automatisk, hvis brugeren har leveret et token.
Test de fire tilstande inden publicering
Forbered komplette, tomme, delvise og fejlede testrespons samt ugyldigt JSON og timeout. Kontroller vist besked, bevarede resultater og antal genoptagelser. Det væsentlige test er, at en fejl aldrig udløser en påstand om fravær af tjenester.
Anvend disse regler til en AI-assistent
Ofte stillede spørgsmål
Beviser en tom liste fravær af toiletter?
Nej. Det angiver blot, at der ikke blev returneret resultater for denne søgning og de anvendte kilder.
Kan man vise et delvist svar?
Ja, hvis de anvendte enheder er gyldige, og du bevarer nødvendige advarsler og begrænsninger.
Skal man genstarte ved hver fejl?
Nej. Ret fejl i parametre eller adgang; begræns genoptagelser til midlertidige problemer og følg tjenestens anvisninger.