API Contract
API는 측정값 제공면이 아니라, 후보값이 실제값처럼 외부로 나가기 전 출력 적격성을 판정하는 계약면이다.
Purpose
GNX Earswet API의 목적은 biofluid candidate value를 빠르게 노출하는 것이 아니다. OEM sensor 또는 adapter가 만든 후보값을 받은 뒤, 발한 품질, 장치 이벤트, marker policy, response schema state를 결합하여 실제값 공개 여부를 결정하는 것이다.
따라서 파트너 시스템은 API 응답을 단순한 measurement JSON으로 취급하지 않는다. 응답은 출력 결정, 접근권한, 제한 사유, 정책 식별자, 증거 식별자를 포함하는 output envelope이다.
Response envelope
| Field | Meaning | Partner rule |
|---|---|---|
candidateValuePresence | 후보값이 내부 처리 대상으로 존재함 | true라도 표시 가능값을 뜻하지 않음 |
rawValueAccess | 실제값 또는 raw value 접근권한 | false면 raw getter, raw endpoint, actual BLE characteristic을 열지 않음 |
outputMode | full, limited, trend-only, remeasurement, blocked, non-value 중 하나 | UI, 저장, 전송, 알림 분기의 1차 기준 |
reasonCode | 품질, 이벤트, 정책, integrity, schema 제한 사유 | 문구가 아니라 기계 판독 가능한 분기 조건 |
evidencePacketId | 결정 trace 식별자 | 지원, 감사, replay 검토용 연결키 |
Endpoint review map
공개 검토에서는 readiness, evaluation, BLE suppression, scenario verification, evidence/replay interface의 역할만 확인한다. 내부 payload mapping, partner-specific schema, raw evidence store, private credential은 공개 문서실에 두지 않는다.
라이선스 테이블에서의 질문은 “어떤 숫자를 반환하는가”가 아니라 “숫자가 존재할 때도 어떤 조건에서 반환하지 않는가”이다.
Non-claims
- 이 API는 의료 진단, 치료 지시, 투약량 결정을 수행하지 않는다.
- 이 API는 OEM sensor의 측정 정확도를 보증하는 계층이 아니다.
- 이 API는 candidate value를 actual value로 자동 승격하지 않는다.
계약 문장: “Earswet API는 candidate value의 외부 출력 가능성을 사전 판정하고, 부적격 상태에서 rawValueAccess=false와 non-value 또는 restricted response를 반환하는 output governance API이다.”