Een API zonder resultaat en een API met fout vereisen twee verschillende benaderingen. Een geslaagde zoekopdracht kan binnen het geraadpleegde gebied geen locaties opleveren. Een netwerkfout, een overschreden limiet of een niet-beschikbare bron verhinderen echter conclusies op basis van de zoekopdracht.
Voor ROOTE controleer je eerst de HTTP-respons, daarna de zakelijke status, de verwachte collectie en de dekking. Deze aanpak voorkomt dat er “geen toilet” wordt getoond wanneer een Services-aanroep is mislukt, of “geen halte” na een verlopen wachttijd.
De drie niveaus van een respons lezen
| Niveau | Te controleren | Mogelijke conclusie |
|---|---|---|
| Transport | Verbinding, timeout en HTTP-status | Is het verzoek geslaagd? |
| Contract | Geldige JSON, versie en verwachte velden | Is de respons bruikbaar? |
| Zakelijk resultaat | status, collecties, dekking, waarschuwingen en meta | Wat is bekend binnen het gevraagde gebied? |
Een HTTP-code 200 is niet voldoende om een zoekopdracht te valideren. De respons kan wijzen op een gedeeltelijke uitvoering of een error-status. Omgekeerd is een 404 op een route geen juiste manier om een lege collectie aan te geven: controleer de URL en het contract.
Begrijpen van success, empty, partial en error
| Status | Aanbevolen verwerking |
|---|---|
| success | Toon entiteiten na validatie en behoud limieten |
| empty | Geef aan dat er geen resultaten zijn voor deze zoekopdracht |
| partial | Toon bruikbare informatie met waarschuwingen |
| error | Presenteer de zoekopdracht als onbeschikbaar; concludeer niet dat er geen locaties zijn |
Het ontbreken van resultaten betreft een verzoek en bekende bronnen. Het bewijst niet de fysieke afwezigheid van diensten. Onvolledige dekking, restrictieve filters of opgelegde limieten kunnen resultaten verminderen.
Een beslisboom voor jouw interface
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.Controleer parameters in de juiste volgorde
Controleer eerst breedte- en lengtegraad, hun volgorde en de verkregen stad. Controleer daarna de eenheid van de straal en het vocabulaire van filters. De API Services gebruikt types=toilets; een kaart-URL gebruikt modes=toilets. Deze parameters horen bij verschillende contracten.
Breid daarna één dimensie tegelijk uit: vergroot de straal binnen de routebeperkingen of verwijder een filter voor een expliciete test. Bewaar de originele query. Als je automatisch uitbreidt, geef de gebruiker het nieuwe gebied door.
Een API-zoekopdracht bouwen rond GPS-coördinaten
Een niet-beschikbare bron behandelen zonder andere te verliezen
Een gedeeltelijke respons kan locaties bevatten van bronnen die wel reageerden terwijl een andere faalde. Behoud deze resultaten, hun attributie en de relevante waarschuwing. Presenteer de lijst niet als volledig en vervang geen ontbrekende velden met misleidende standaardwaarden.
Oudere, in cache bewaarde informatie kan nuttig zijn indien dit beleid toestaat. Het moet als oud worden aangeduid. Het tijdstip van jouw verzoek ververst niet de originele observatie.
Berichten en herstelacties aanpassen
| Situatie | Aan te passen bericht voor jouw interface | Actie |
|---|---|---|
| empty | Geen resultaten in dit gebied met deze filters | Wijzig het gebied of de filters |
| partial | Sommige resultaten zijn beschikbaar; de zoekopdracht is incompleet | Toon resultaten en waarschuwing |
| Validatiefout | De zoekopdracht bevat een ongeldig parameter | Corrigeer het verzoek |
| Authenticatie of rechten | Deze toegang staat deze zoekopdracht niet toe | Controleer het account of token |
| Limiet of onbeschikbaarheid | De zoekopdracht is tijdelijk onbeschikbaar | Volg de herstelinstructies |
Bij een 429 raadpleeg de serviceregels en eventuele Retry-After header. Een 400 fout vereist correctie van argumenten; herhalen lost dit niet op. Zet een 401 fout niet automatisch om in anonieme oproep als de gebruiker een token heeft verstrekt.
Test de vier statussen voor publicatie
Bereid volledige, lege, gedeeltelijke en fout-responses, evenals ongeldige JSON en timeouts voor. Controleer weergegeven berichten, behouden resultaten en aantal herhalingen. Essentieel is dat een storing nooit leidt tot de conclusie dat er geen diensten zijn.
Regels toepassen op een AI-assistent
Mobility dataformaten begrijpen
Veelgestelde vragen
Bewijst een lege lijst het ontbreken van toiletten?
Nee. Het geeft alleen aan dat er geen resultaten zijn voor deze zoekopdracht en geraadpleegde bronnen.
Mag een gedeeltelijke respons worden getoond?
Ja, als gebruikte entiteiten geldig zijn en waarschuwingen en limieten worden behouden.
Moet elke fout opnieuw worden geprobeerd?
Nee. Corrigeer parameter- en toegangsproblemen; beperk herhalingen bij tijdelijke fouten en volg de service-instructies.