피드로 돌아가기
Dev.toBackend
원문 읽기
Boolean 응답을 Granular Outcome으로 확장한 검증 API 설계
Verify is not just true or false, granular outcomes on /verify
AI 요약
Context
기존 GET /api/v1/verify/{signature_id} 엔드포인트의 Boolean 기반 응답 체계로 인한 상세 분석 불가 문제 발생. 단순 성공/실패 여부만으로는 규제 기관이나 법적 증거 제출 시 필요한 포렌식 수준의 원인 파악이 불가능한 구조적 한계 직면.
Technical Solution
- 단순 Boolean 응답에 verification_detail 객체를 추가한 확장 스키마 설계
- signer_key_match, signature_valid, algorithm_match, agent_active 등 4가지 세부 검증 축(Sub-checks) 정의
- 검증 결과에 따른 6가지 상태(valid, invalid_signature, signer_key_changed 등)의 validation_label 도입
- 기존 클라이언트의 하위 호환성 유지를 위해 신규 필드를 Optional로 처리한 Backwards-compatible 설계
- API 응답 값의 존재 여부에 따라 UI 그리드를 조건부 렌더링하는 프런트엔드 로직 적용
실천 포인트
- 단순 상태 값 반환 API 설계 시 향후 디버깅 및 감사(Audit)를 위한 상세 컨텍스트 확장 가능성을 고려할 것 - API 스키마 변경 시 기존 클라이언트 영향도를 최소화하기 위해 신규 필드는 Optional로 추가하고 기본 구조를 유지할 것 - 비즈니스 로직의 결과물에 포렌식 관점의 레이블을 부여하여 데이터의 추적 가능성(Traceability)을 확보할 것