JSONPath로 큰 API 응답 디버깅하기

문제 상황

API 응답에 수백 개 필드가 있으면 전체 문서를 눈으로 비교하는 동안 실제 원인을 놓치기 쉽습니다. 배열 안의 오류 코드, 환경마다 달라지는 상태, 누락된 다음 페이지 링크, 로그와 대조할 요청 ID를 각각 좁혀 확인해야 디버깅 속도가 빨라집니다.

공식 출처와 표준

다음 공식 문서는 이 작업 흐름에서 다루는 형식과 보안 경계의 기준입니다. 도구별 실행 검증은 위에 별도로 기록합니다.

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format

  RFC Editor / IETF

• RFC 9535: JSONPath: Query Expressions for JSON

  RFC Editor / IETF

이럴 때 사용하세요

• 실패한 API 응답이 유효한 JSON이지만 너무 커서 눈으로 비교하기 어려울 때
• 같은 payload에서 요청 ID, 상태, 오류 코드, 페이지 링크를 따로 확인해야 할 때
• 프런트엔드 오류가 환경마다 달라지는 중첩 필드 하나에 의존할 때
• 전체 운영 응답 대신 재현 가능한 짧은 디버깅 기록을 공유해야 할 때

단계

1. 1단계

   원본 응답과 HTTP 문맥 보관

   응답 본문을 복사하고 상태 코드, content-type, cache, CORS, 요청 ID 헤더처럼 증상과 관련된 정보를 함께 기록합니다. 헤더가 의심되면 HTTP Header Parser로 본문과 분리해 확인하세요.

2. 2단계

   JSON 문법 먼저 확인

   응답이 한 줄로 압축돼 있으면 JSON Formatter로 구조를 읽고, 로그에서 복사했거나 일부가 잘렸다면 JSON Validator로 오류 행과 열을 먼저 수정합니다.

3. 3단계

   증상과 연결된 필드만 추출

   $.meta.requestId, $.data.items[*].status, $.errors[*].code, $.links.next처럼 질문 하나에 답하는 표현식을 각각 실행합니다. 오류 배열을 좁혀야 하면 $.errors[?(@.severity == "critical")].code 같은 필터를 사용합니다.

4. 4단계

   환경별 결과를 같은 표현식으로 비교

   개발, 스테이징, 운영, 실패한 fixture에 동일한 표현식을 실행합니다. 전체 응답 diff보다 일치 경로와 값만 비교하면 어떤 필드가 사라지거나 달라졌는지 빠르게 확인할 수 있습니다.

5. 5단계

   수정 사항에 표현식과 결과 첨부

   Pull request, 테스트 케이스, 지원 기록에 JSONPath 표현식과 필요한 결과만 남깁니다. 운영 데이터의 이메일, 토큰, 계정 ID는 공유 전에 반드시 가리세요.

예시

{
  "meta": { "requestId": "req_9f21" },
  "data": { "items": [
    { "id": 1, "status": "active" },
    { "id": 2, "status": "pending" }
  ] },
  "links": { "next": "https://api.example.com/users?page=2" }
}

$.meta.requestId -> req_9f21
$.data.items[*].status -> active, pending
$.links.next -> https://api.example.com/users?page=2

흔한 실수

자주 묻는 질문