반응형

바쁜 분은 이것만

  1. 한 줄로 붙은 JSON은 curl -s 주소 | python3 -m json.tool로 줄 바꿈·들여쓰기
  2. 한글이 서울처럼 나오면 --no-ensure-ascii 추가
  3. 헤더는 -H '이름: 값', 상태코드만은 -s -o /dev/null -w '%{http_code}\n', 저장은 -o 파일.json

파이썬으로 API 수집 코드를 짜기 전에, 터미널에서 응답이 어떻게 생겼는지 먼저 보는 습관이 있어요. 맥에는 curl이 기본으로 들어 있어서 따로 설치할 것도 없습니다. 이 글은 키 없이 쓸 수 있는 테스트용 API httpbin.org로 직접 돌려 본 내용이에요.

1. 기본: curl -s 로 응답 받기

httpbin의 /base64/... 주소는 뒤에 붙인 글자를 풀어서 그대로 돌려줘요. 서버가 한 줄로 붙여 보내는 JSON을 흉내 내기 좋아서 예제로 썼습니다.

$ U='https://httpbin.org/base64/eyJjaXR5Ijoi7ISc7Jq4IiwidGVtcCI6My41LCJ0YWdzIjpbIuunkeydjCIsIuuwlOuejCJdLCJvayI6dHJ1ZX0='
$ curl -s "$U"
{"city":"서울","temp":3.5,"tags":["맑음","바람"],"ok":true}

-s(silent)는 진행률 표시를 끄는 옵션이에요. 파이프(|)로 다른 명령에 넘길 때 진행률 표가 섞이지 않게 거의 항상 붙입니다. 주소에 ?나 &가 들어가면 셸이 다르게 읽을 수 있으니 따옴표로 감싸 주세요.

2. python3 -m json.tool 로 예쁘게 보기

짧으면 괜찮지만 실제 API 응답은 수백 개 항목이 한 줄로 오는 경우가 많아요. 파이썬에 들어 있는 json.tool에 넘기면 줄을 바꾸고 들여쓰기를 해 줍니다.

$ curl -s "$U" | python3 -m json.tool
{
    "city": "서울",
    "temp": 3.5,
    "tags": [
        "맑음",
        "바람"
    ],
    "ok": true
}

모양은 좋아졌는데 한글이 서울로 바뀌었어요. curl만 했을 땐 "서울"이 잘 보였으니 깨진 게 아니라 json.tool이 바꾼 겁니다.

3. 한글이 \uXXXX 로 나올 때: --no-ensure-ascii

json.tool은 기본으로 영어(ASCII) 밖의 글자를 \uXXXX로 적어요. 파이썬 json.dumps()의 ensure_ascii=True가 기본값인 것과 같은 이유예요. 끄는 옵션이 --no-ensure-ascii입니다.

$ curl -s "$U" | python3 -m json.tool --no-ensure-ascii
{
    "city": "서울",
    "temp": 3.5,
    "tags": [
        "맑음",
        "바람"
    ],
    "ok": true
}

서버가 처음부터 \uXXXX로 보내는 경우도 있어요. 이때도 같은 옵션으로 한글로 바뀝니다.

$ curl -s https://httpbin.org/base64/eyJjaXR5IjogIlx1YzExY1x1YzZiOCIsICJ0ZW1wIjogMy41fQ==
{"city": "서울", "temp": 3.5}
$ curl -s https://httpbin.org/base64/eyJjaXR5IjogIlx1YzExY1x1YzZiOCIsICJ0ZW1wIjogMy41fQ== | python3 -m json.tool --no-ensure-ascii
{
    "city": "서울",
    "temp": 3.5
}

들여쓰기 칸 수와 키 정렬도 바꿀 수 있어요.

$ curl -s "$U" | python3 -m json.tool --no-ensure-ascii --indent 2 --sort-keys
{
  "city": "서울",
  "ok": true,
  "tags": [
    "맑음",
    "바람"
  ],
  "temp": 3.5
}

Homebrew로 설치한 Python 3.14와 맥에 기본으로 깔린 /usr/bin/python3(3.9.6) 둘 다 --no-ensure-ascii가 동작했어요. 이 맥에는 /usr/bin/jq(jq-1.7.1-apple)도 있어서 curl -s "$U" | jq .로 보면 처음부터 한글로, 2칸 들여쓰기로 나옵니다.

응답이 JSON이 아니면 이런 메시지가 나와요.

$ curl -s https://httpbin.org/html | python3 -m json.tool
Expecting value: line 1 column 1 (char 0)

"첫 글자부터 JSON이 아니다"라는 뜻이에요. 주소가 틀려 HTML 에러 페이지가 왔거나 빈 응답일 때 자주 봅니다. | python3 -m json.tool을 떼고 원래 응답을 먼저 확인해 보세요.

4. 헤더 붙이기: -H

-H '이름: 값'을 여러 번 쓰면 헤더를 여러 개 보낼 수 있어요. httpbin의 /headers는 내가 보낸 헤더를 그대로 돌려줘서 확인하기 좋습니다.

$ curl -s https://httpbin.org/headers -H 'accept: application/json' -H 'authorization: bearer TEST_KEY_1234' | python3 -m json.tool
{
    "headers": {
        "Accept": "application/json",
        "Authorization": "bearer TEST_KEY_1234",
        "Host": "httpbin.org",
        "User-Agent": "curl/8.7.1"
    }
}

키를 요구하는 API는 대부분 이렇게 authorization 헤더에 키를 넣어요. 예를 들어 로스트아크 오픈API 거래소 시세 매일 자동 수집하기에서 쓴 로스트아크 오픈API는 authorization: bearer 발급받은키 형식입니다. 파이썬 코드에서도 같은 헤더를 넣고 있어요.

# 형식만 (실제 키는 환경 변수로)
curl -s 'https://developer-lostark.game.onstove.com/news/notices' \
  -H 'accept: application/json' \
  -H "authorization: bearer $LOSTARK_API_KEY"

키를 명령에 직접 적으면 셸 히스토리(~/.zsh_history)에 남으니 환경 변수에 넣어 두고 부르는 게 좋아요. 이때 따옴표 종류를 조심해야 합니다. 큰따옴표 안의 $변수는 값으로 바뀌지만 작은따옴표 안은 글자 그대로 나가요.

$ MYKEY=TEST_KEY_1234; curl -s https://httpbin.org/headers -H "authorization: bearer $MYKEY" | python3 -m json.tool
{
    "headers": {
        "Accept": "*/*",
        "Authorization": "bearer TEST_KEY_1234",
        "Host": "httpbin.org",
        "User-Agent": "curl/8.7.1"
    }
}
$ curl -s https://httpbin.org/headers -H 'authorization: bearer $MYKEY' | python3 -m json.tool
{
    "headers": {
        "Accept": "*/*",
        "Authorization": "bearer $MYKEY",
        "Host": "httpbin.org",
        "User-Agent": "curl/8.7.1"
    }
}

401(인증 실패)이 나는데 키는 맞는 것 같다면 이 따옴표부터 확인해 보세요.

5. 상태코드만 보기: -w '%{http_code}'

본문은 필요 없고 "살아 있나"만 보고 싶을 때예요. -o /dev/null로 본문을 버리고 -w로 상태코드만 찍습니다.

$ curl -s -o /dev/null -w '%{http_code}\n' https://httpbin.org/json
200
$ curl -s -o /dev/null -w '%{http_code}\n' https://httpbin.org/status/404
404
$ curl -s -o /dev/null -w '%{http_code}\n' https://httpbin.org/status/503
503

\n을 빼면 숫자 뒤에 줄 바꿈이 없어 프롬프트가 바로 붙어요. 걸린 시간과 받은 크기도 같이 볼 수 있습니다.

$ curl -s -o /dev/null -w '%{http_code} %{time_total}s %{size_download}bytes\n' https://httpbin.org/json
200 0.656556s 429bytes

본문과 상태코드를 같이 보려면 -o를 빼고 앞에 줄 바꿈을 넣어요.

$ curl -s -w '\n%{http_code}\n' "$U"
{"city":"서울","temp":3.5,"tags":["맑음","바람"],"ok":true}
200

주의할 점은, curl은 404나 401을 받아도 명령 자체는 성공으로 끝난다는 거예요. 스크립트에서 실패를 잡으려면 -f를 붙이고, -S를 같이 쓰면 -s로 숨긴 에러 메시지는 보여 줍니다.

$ curl -s https://httpbin.org/status/401; echo "[$?]"
[0]
$ curl -sSf https://httpbin.org/status/401
curl: (56) The requested URL returned error: 401

이 맥의 curl 8.7.1에서는 이때 종료 코드가 56이었어요. 0이 아니라는 점만 보고 판단하면 됩니다.

6. 응답을 파일로 저장: -o

$ curl -s -o resp.json "$U"
$ ls -l resp.json
-rw-r--r--@ 65 resp.json
$ python3 -m json.tool --no-ensure-ascii resp.json pretty.json
$ cat pretty.json
{
    "city": "서울",
    "temp": 3.5,
    "tags": [
        "맑음",
        "바람"
    ],
    "ok": true
}

json.tool에 파일 이름을 두 개 주면 앞의 파일을 읽어 뒤의 파일로 저장해요. 한 번 저장해 두면 API를 다시 부르지 않고 파이썬 코드를 여러 번 시험할 수 있어서, 하루 호출 수 제한이 있는 API에서 특히 편합니다. 날짜를 파일 이름에 넣으면 날마다 따로 쌓여요.

$ curl -s https://httpbin.org/json | python3 -m json.tool > slides_$(date +%F).json
$ ls
pretty.json
resp.json
slides_2026-11-08.json

저장하면서 상태코드도 보고 싶으면 -o와 -w를 같이 쓰면 돼요. 본문은 파일로, 상태코드는 화면으로 갑니다.

$ curl -s -w '%{http_code}\n' -o resp.json "$U"
200

응답 헤더까지 보고 싶을 땐 -i를 붙여요. content-type: application/json인지 확인할 때 씁니다.

$ curl -s -i https://httpbin.org/json | head -8
HTTP/2 200
access-control-allow-credentials: true
access-control-allow-origin: *
access-control-expose-headers: Retry-After, RateLimit, RateLimit-Policy
content-length: 429
content-type: application/json
x-content-type-options: nosniff
date: Sun, 08 Nov 2026 06:42:06 GMT

정리

하고 싶은 것 명령
JSON 예쁘게 curl -s 주소 | python3 -m json.tool
한글 \uXXXX → 한글 ... | python3 -m json.tool --no-ensure-ascii
헤더(키) 보내기 -H "authorization: bearer $KEY" (큰따옴표)
상태코드만 -s -o /dev/null -w '%{http_code}\n'
4xx·5xx를 실패로 -sSf
파일 저장 -o resp.json, 정리본은 json.tool 입력 출력
응답 헤더 확인 -i

참고: curl(1) man page — -s, -S, -f, -H, -o, -i, -w(write-out 변수 http_code·time_total·size_download) / Python 공식 문서 — json 모듈 Command Line Interface(json.tool: --no-ensure-ascii, --indent, --sort-keys) / httpbin.org

반응형

+ Recent posts