API 요청 전에 JSON 검증하기

왜 전송 전에 검증하는가

API 요청이 실패하면 오류 메시지는 인증, 권한, 스키마 검증, 잘못된 JSON 중 하나를 가리킬 수 있습니다. 먼저 JSON 본문을 검증하면, 요청이 서버에 도달하기 전에 한 부류의 실패를 통째로 없앨 수 있습니다. 또 복사한 cURL 명령, Postman 본문, 웹훅 샘플, 통합 테스트를 검토하기도 쉬워집니다.

실행할 구문 체크

엄격한 JSON 검증은 본문이 JSON으로 파싱되고, 포매팅된 출력이 보내려는 것과 일치하는지 확인해야 합니다.

• 모든 문자열과 객체 키가 큰따옴표를 사용함
• 주석이나 후행 콤마가 없음
• 불리언은 True/False가 아니라 true/false
• 누락된 값은 undefined가 아니라 null 또는 키 생략
• 최상위 값이 엔드포인트가 기대하는 것과 일치함

헤더도 중요하다

유효한 JSON 본문이라도 요청이 올바른 Content-Type을 선언하지 않으면 실패할 수 있습니다. 대부분의 JSON API에는 Content-Type: application/json을 보내세요. 엔드포인트가 Accept도 확인한다면 Accept: application/json을 포함해 클라이언트와 서버가 페이로드 형식에 합의하도록 하세요.

잘못된 요청 본문

{ userId: 42, active: True, tags: ['beta',], }

수정된 요청 본문

{ "userId": 42, "active": true, "tags": ["beta"] }

구문 검증 이후

구문 검증은 문서가 파싱 가능함만 증명합니다. 프로덕션 요청에서는 필수 필드, 알 수 없는 필드, 값 타입, 배열 길이, 열거 값, 날짜 문자열, 숫자 ID를 숫자/문자열 중 무엇으로 다룰지도 확인하세요.

디버깅 팁

서버가 여전히 유효한 JSON을 거부한다면, 포매팅된 요청 본문을 알려진 정상 샘플과 비교하세요. 시맨틱 JSON diff는 키 순서를 무시하고 실제 값 변화를 찾기 때문에, 서로 다른 도구가 생성한 payload에 특히 유용합니다.

작은 fetch + Ajv 래퍼

응답 본문을 앱 코드에 넘기기 전에 알려진 스키마로 검증하세요. 모듈 로드 시 스키마를 한 번 컴파일하고, 모든 호출을 보호합니다: const validate = ajv.compile(schema); const res = await fetch(url); const data = await res.json(); if (!validate(data)) throw new Error("Schema mismatch: " + ajv.errorsText(validate.errors)); return data; — 그러면 상류의 계약 위반이 다섯 단계 아래가 아니라 경계에서 드러납니다.