결과가 없는 API와 오류가 발생한 API는 서로 다른 처리가 필요합니다. 성공한 검색도 조회 범위 내에 장소를 반환하지 않을 수 있습니다. 반면 네트워크 오류, 한도 초과 또는 소스 비가용성은 검색으로 결론을 낼 수 없게 합니다.
ROOTE에서는 HTTP 응답과 업무 상태, 예상되는 컬렉션, 적용 범위를 확인하세요. 이 과정은 서비스 호출 실패 시 "화장실 없음" 또는 지연 초과 후 "정류장 없음"을 방지합니다.
응답의 세 가지 레벨 읽기
| 레벨 | 확인할 항목 | 가능한 결론 |
|---|---|---|
| 전송 | 연결, 지연, HTTP 상태 | 요청이 성공했나요? |
| 계약 | 유효한 JSON, 버전 및 예상 필드 | 응답을 활용할 수 있나요? |
| 업무 결과 | status, collections, coverage, warnings 및 meta | 요청된 범위 내에서 무엇을 알 수 있나요? |
HTTP 200 코드는 검색 검증에 충분하지 않습니다. 응답은 부분 실행이나 error 상태를 알릴 수 있습니다. 반대로 경로의 404는 빈 컬렉션을 표현하는 정상적 방법이 아닙니다: URL과 계약을 확인하세요.
success, empty, partial, error 상태 이해하기
| 상태 | 권장 처리 방법 |
|---|---|
| success | 검증 후 엔터티 표시 및 한도 유지 |
| empty | 이 검색에 대해 결과가 없음을 알림 |
| partial | 사용 가능한 정보와 경고를 표시 |
| error | 검색이 불가함을 나타내고 장소 부재를 단정하지 않음 |
결과 부재는 알려진 쿼리와 소스에 국한됩니다. 이는 물리적으로 서비스가 없음을 입증하지 않습니다. 불완전한 적용 범위, 엄격한 필터 또는 한도가 결과를 줄일 수 있습니다.
인터페이스를 위한 의사결정 트리
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.매개변수를 올바른 순서로 확인
먼저 위도와 경도, 순서 및 얻은 도시를 확인하고, 반경 단위와 필터 용어를 검증하세요. Services API는 types=toilets를 사용하고, 지도 URL은 modes=toilets를 사용합니다. 이들은 서로 다른 계약에 속합니다.
그다음 한 차원씩 확장하세요: 경로 한도 내에서 반경을 늘리거나 특정 필터를 제거해 명확한 테스트를 수행하세요. 초기 요청 기록을 유지하고 자동 확장 시에는 사용자에게 새 범위를 알려야 합니다.
다른 소스를 잃지 않고 비가용 소스 처리하기
부분 응답은 한 소스가 실패했어도 다른 소스에서 응답한 장소를 포함할 수 있습니다. 이 결과, 출처 및 적절한 경고를 유지하세요. 목록을 완전한 것으로 제시하지 말고, 누락된 필드를 잘못된 기본값으로 대체하지 마세요.
캐시에 보관된 오래된 정보도 정책이 허용하면 유용할 수 있습니다. 이 정보는 반드시 오래된 것으로 식별되어야 합니다. 요청 시각이 원래 관측 시각을 갱신하지 않습니다.
메시지 및 재시도 조정하기
| 상황 | 인터페이스에 맞는 메시지 | 조치 |
|---|---|---|
| empty | 이 영역과 필터에 대해 반환된 결과가 없습니다 | 영역 또는 필터 수정 |
| partial | 일부 결과는 있으나 검색이 불완전합니다 | 결과와 경고 표시 |
| 검증 오류 | 검색에 잘못된 매개변수가 포함되어 있습니다 | 요청 수정 |
| 인증 또는 권한 | 이 접근은 해당 검색을 허용하지 않습니다 | 계정 또는 토큰 확인 |
| 한도 또는 비가용 | 검색이 일시적으로 불가능합니다 | 재시도 지침 준수 |
429 오류는 서비스 지침과 가능하다면 Retry-After 헤더를 확인하세요. 400 오류는 인수 수정을 요구하며 반복 요청으론 해결되지 않습니다. 사용자가 토큰을 제공했다면 401을 자동 익명 호출로 전환하지 마세요.
게시 전에 네 가지 상태 테스트하기
완전, 빈, 부분, 오류 응답과 함께 유효하지 않은 JSON 및 타임아웃 테스트를 준비하세요. 표시 메시지, 보존 결과 및 재시도 횟수를 확인하세요. 핵심 테스트는 장애 발생 시 서비스 부재를 주장하지 않는 것입니다.
자주 묻는 질문
빈 목록이 화장실 부재를 증명하나요?
아니요. 해당 검색과 조회한 소스에 대한 결과가 없을 뿐입니다.
부분 응답을 표시해도 되나요?
네, 사용된 엔터티가 유효하고 필요한 경고와 한도를 유지한다면 가능합니다.
모든 오류를 재시도해야 하나요?
아니요. 매개변수나 접근 오류는 수정하고, 일시적 문제는 재시도를 제한하며 서비스 지침을 준수하세요.