API 응답 JSON 읽는 법 - 중괄호부터 중첩 구조까지 초보자를 위한 해석 가이드
개발자 도구를 열었더니 한 줄로 뭉쳐 나온 JSON, 어디서부터 봐야 할까요? 중괄호와 대괄호의 의미, 중첩 구조를 따라가는 순서, 보기 좋게 정리해 주는 무료 도구까지 초보자 눈높이로 설명합니다.
API 연동을 처음 해 보면 누구나 비슷한 벽에 부딪힙니다. 요청은 분명 성공했는데 돌아온 응답이 중괄호와 따옴표로 뒤엉킨 한 덩어리 텍스트라서, 내가 필요한 값이 어디에 있는지 찾기가 막막합니다. 다행히 API 응답 JSON 읽는 법은 외워야 할 규칙이 몇 가지 안 됩니다. 값의 종류 6가지와 괄호 2종류만 구분할 수 있으면, 어떤 서비스의 API 응답이든 같은 방식으로 해석할 수 있습니다.
JSON이 무엇인지 1분 만에 이해하기
JSON(JavaScript Object Notation)은 서버와 프로그램이 데이터를 주고받을 때 가장 널리 쓰는 텍스트 형식입니다. 국제 표준 문서인 RFC 8259로 정의되어 있고, 이름에 자바스크립트가 들어가지만 파이썬, 자바, PHP 등 거의 모든 언어에서 그대로 사용합니다. 핵심 구조는 단순합니다. 이름(키)과 값이 쌍을 이루고, 그 쌍들이 모여 하나의 데이터 묶음이 됩니다.
JSON에 들어갈 수 있는 값의 종류는 아래 6가지가 전부입니다.
| 타입 | 예시 | 설명 |
|---|---|---|
| 문자열 | "hello" | 반드시 큰따옴표로 감쌉니다 |
| 숫자 | 42, 3.14 | 따옴표 없이 씁니다 |
| 불리언 | true, false | 참과 거짓 두 가지뿐입니다 |
| null | null | 값이 없음을 뜻합니다 |
| 객체 | { "a": 1 } | 중괄호로 감싼 키와 값의 묶음 |
| 배열 | [1, 2, 3] | 대괄호로 감싼 값의 목록 |
중괄호와 대괄호, 구조 읽는 순서
JSON을 읽을 때 가장 먼저 볼 것은 괄호입니다. 중괄호 { }는 객체이고, 이름표가 붙은 서랍장이라고 생각하면 됩니다. 대괄호 [ ]는 배열이고, 순서대로 늘어선 목록입니다. 배열 안의 항목은 이름이 없는 대신 0부터 시작하는 번호(인덱스)로 접근합니다.
바깥에서 안쪽으로 읽기
아무리 복잡해 보이는 응답도 읽는 순서는 항상 같습니다.
- 1단계: 가장 바깥 괄호가 { 인지 [ 인지 확인합니다. 전체가 객체 하나인지, 목록인지가 여기서 결정됩니다.
- 2단계: 첫 번째 깊이의 키 이름만 훑어봅니다. status, data, error 같은 키 몇 개가 응답 전체의 지도가 됩니다.
- 3단계: 필요한 키 하나만 골라 그 안으로 들어갑니다. 나머지 키는 무시해도 됩니다.
JSON을 잘 읽는 사람은 전체를 다 읽지 않습니다. 바깥 구조에서 지도를 먼저 그린 다음, 필요한 가지 하나만 따라 내려가는 것이 핵심입니다.
실제 API 응답 예제로 연습하기
쇼핑몰 API가 돌려주는 전형적인 응답을 예로 들어 보겠습니다.
{
"status": "success",
"data": {
"total": 2,
"items": [
{ "id": 101, "name": "무선 마우스", "stock": true },
{ "id": 102, "name": "기계식 키보드", "stock": false }
]
}
}가장 바깥은 객체이고, 첫 깊이의 키는 status와 data 두 개뿐입니다. 요청이 성공했는지는 status로 확인하고, 상품 목록이 필요하면 data 안의 items 배열로 들어가면 됩니다. items 안에는 객체 2개가 순서대로 들어 있습니다.
경로 표기법으로 위치 읽기
개발 문서나 코드에서는 점(.)과 대괄호로 값의 위치를 표현합니다. 첫 번째 상품의 이름은 data.items[0].name이고 값은 "무선 마우스"입니다. 배열 번호가 1이 아니라 0부터 시작한다는 점만 기억하면, 두 번째 상품은 items[1]이 됩니다. 이 표기법에 익숙해지면 API 문서를 읽는 속도가 눈에 띄게 빨라집니다.
JSON을 보기 좋게 정리해 주는 도구
한 줄로 뭉쳐서 도착한 응답을 눈으로만 해석하는 것은 비효율적입니다. 도구를 쓰면 들여쓰기와 색상 구분이 자동으로 적용됩니다.
- 브라우저 개발자 도구: F12를 눌러 네트워크(Network) 탭을 열면, Preview 화면에서 JSON을 접었다 펼 수 있는 트리 형태로 보여줍니다.
- 온라인 JSON 포매터: 응답을 붙여넣기만 하면 들여쓰기 정렬과 문법 검사를 한 번에 해 줍니다. 설치가 필요 없어 가장 빠릅니다.
- VS Code: 새 파일에 붙여넣고 언어를 JSON으로 지정하면 자동 정렬(Shift+Alt+F)과 오류 밑줄 표시를 지원합니다.
- jq: 터미널에서 JSON을 필터링하고 가공하는 명령줄 도구로, 자동화 스크립트에 자주 쓰입니다.
요즘 개발 작업은 이렇게 설치 없이 브라우저에서 바로 쓰는 웹 도구가 기본값이 됐습니다. 웹사이트에 올릴 사진 용량을 줄일 때 이미지 압축 도구를 열고, 화면 색 조합을 정할 때 컬러 팔레트 생성기를 쓰는 것처럼, JSON 포매터도 즐겨찾기에 하나 등록해 두면 응답 확인에 드는 시간이 크게 줄어듭니다.
자주 만나는 오류와 해결법
JSON 문법은 엄격해서 사소한 실수 하나로도 파싱 오류가 납니다. 초보자가 가장 자주 겪는 사례는 다음과 같습니다.
- 작은따옴표 사용: JSON의 키와 문자열에는 큰따옴표만 허용됩니다. 작은따옴표를 쓰면 파서가 거부합니다.
- 마지막 쉼표(trailing comma): 마지막 항목 뒤에 쉼표가 남아 있으면 오류입니다. 자바스크립트 코드에서는 허용되지만 JSON에서는 안 됩니다.
- HTTP 200인데 내용은 실패: 상태 코드가 200이어도 본문의 status나 error 필드에 실패 정보를 담아 주는 API가 많습니다. 코드만 보지 말고 본문까지 확인해야 합니다.
오늘 바로 해 볼 액션은 두 가지입니다. 첫째, 자주 다루는 API 응답 하나를 포매터에 붙여넣고 첫 깊이의 키 이름들을 지도처럼 메모해 보세요. 둘째, 필요한 값 하나를 골라 data.items[0].name 같은 경로 표기로 직접 적어 보세요. 이 두 가지만 연습해도 다음부터는 어떤 응답을 만나든 구조부터 파악하는 습관이 자리 잡습니다.
