curl로 API 테스트하는 방법, 자주 쓰는 옵션만 정리해봤다

API 연동 작업을 하다 보면 브라우저에서는 요청이 안 되는데 서버에서는 되는지 확인해야 하거나, 반대로 서버에서 실제로 어떤 응답을 받고 있는지 확인해야 할 때가 있다.

 

이럴 때 자주 사용하는 명령어가 curl이다.

 

처음에는 단순히 URL을 호출하는 명령어 정도로 생각했는데, 사용하다 보니 응답 헤더를 확인하거나 HTTP/HTTPS 통신 상태를 비교하고, 요청·응답 내용을 자세하게 확인할 때도 꽤 유용했다.

 

특히 API 문제가 생겼을 때는 브라우저에서만 확인하는 것보다 서버에서 직접 curl을 실행해보면 문제가 API 자체인지, 브라우저인지, 서버의 네트워크 환경인지 범위를 좁히는 데 도움이 된다.

 

이번에는 API 테스트할 때 자주 사용하는 curl 명령어를 정리해봤다.

---

curl이 뭘까?

curl은 URL을 이용해서 서버와 데이터를 주고받을 수 있는 명령줄 도구다.

가장 간단한 사용법은 URL을 그대로 입력하는 것이다.

 

curl https://example.com/api/test

 

GET 방식의 API라면 이것만으로도 요청을 보내고 응답 내용을 터미널에서 확인할 수 있다.

예를 들어 API가 JSON을 반환한다면:

 

{
  "result": "success",
  "data": [
    {
      "id": 1,
      "name": "sample"
    }
  ]
}

 

같은 결과가 터미널에 바로 출력된다.

curl 명령어로 API GET 요청을 테스트한 화면 예시

---

응답 헤더까지 확인하려면 -i

API가 데이터를 정상적으로 반환하는지도 중요하지만 문제를 확인할 때는 HTTP 상태코드도 봐야 한다.

이때 사용할 수 있는 옵션이 -i다.

 

curl -i https://example.com/api/test

 

그러면 응답 본문뿐 아니라 응답 헤더도 같이 출력된다.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 125
Date: ...

{"result":"success"}

 

여기서:

HTTP/1.1 200 OK

 

같은 상태코드를 확인할 수 있다.

API 문제를 확인할 때 200, 403, 404, 500 등의 상태코드가 무엇인지 보는 것만으로도 원인을 좁히는 데 도움이 된다.

---

헤더만 확인하려면 -I

응답 데이터까지 받을 필요 없이 헤더만 확인하고 싶다면 대문자 -I를 사용할 수 있다.

 

curl -I https://example.com

 

예를 들면:

HTTP/2 200
content-type: text/html
content-length: 1234
server: nginx

 

처럼 확인할 수 있다.

다만 여기서 하나 알아둘 점이 있다.

-I는 단순히 GET 요청을 보내고 본문만 숨기는 옵션이 아니라 HEAD 요청을 사용한다.

따라서 API 서버가 HEAD 요청을 지원하지 않거나 GET과 HEAD를 다르게 처리한다면 결과가 다를 수도 있다.

GET 요청의 실제 응답 헤더를 확인하려는 목적이라면 -i나 -D 같은 방법을 사용하는 게 더 적절할 수 있다.

이건 처음 사용할 때 은근히 헷갈리기 쉬운 부분이다.

---

통신 과정을 자세하게 보고 싶다면 -v

API 호출이 안 될 때 내가 자주 확인하게 되는 옵션은 -v다.

 

curl -v https://example.com/api/test

 

v는 verbose의 의미로, 통신 과정을 자세하게 보여준다.

예를 들면:

* Trying 192.0.2.10:443...
* Connected to example.com
* TLSv1.2 ...
> GET /api/test HTTP/1.1
> Host: example.com
> User-Agent: curl/...
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
{"result":"success"}

 

이 결과를 보면 단순히 API 결과뿐만 아니라

• 어느 IP와 연결했는지
• 어느 포트를 사용하는지
• TLS 연결은 어떻게 되었는지
• 어떤 HTTP 요청을 보냈는지
• 서버가 어떤 상태코드를 반환했는지

등을 확인할 수 있다.

그래서 단순 데이터 확인보다 통신 문제를 확인할 때 특히 유용하다.

curl verbose 옵션으로 API 연결 과정과 HTTP 상태를 확인한 화면 예시

---

HTTP와 HTTPS를 비교해볼 수도 있다

예를 들어 같은 서비스가 HTTP와 HTTPS를 모두 제공하고 있다면 각각 호출해볼 수 있다.

 

curl -v http://example.com/api/test

 

그리고:

 

curl -v https://example.com/api/test

 

두 결과를 비교하는 것이다.

실제로 API 문제를 확인하다 보면 브라우저에서는 단순히

ERR_CONNECTION_RESET

 

정도로만 보이던 문제가 서버에서 curl로 직접 요청했을 때 좀 더 구체적으로 드러나는 경우가 있다.

예전에 확인했던 문제 중에는 HTTP 요청이 처음에는 정상적으로 연결되고 200 OK까지 반환했는데 응답 데이터를 받는 도중 연결이 종료되는 현상도 있었다. 반면 같은 요청을 HTTPS로 보내면 정상적으로 완료됐다.

이런 경우에는 단순히:

HTTP 200이니까 API는 정상이다.

라고 판단하면 안 된다.

---

200 OK가 나왔다고 응답이 끝난 건 아니다

이 부분은 실제로 API를 확인하면서 꽤 중요했다.

예를 들어:

HTTP/1.1 200 OK

<data>
    ...

 

까지 나왔다고 해보자.

상태코드는 200 OK다.

그런데 데이터를 전송하는 도중 연결이 끊긴다면 클라이언트는 전체 응답을 받지 못한다.

즉,

연결
 ↓
HTTP 200
 ↓
응답 데이터 전송
 ↓
응답 완료

 

까지 정상적으로 끝나야 한다.

200 OK는 서버가 응답을 시작했다는 사실만으로 전체 본문 전송 완료를 보장하지 않는다.

그래서 대용량 API나 WFS처럼 응답이 큰 요청을 테스트할 때는 마지막까지 정상적으로 수신되는지도 같이 봐야 한다.

---

결과를 파일로 저장하려면 -o

API 결과가 너무 길면 터미널에서 확인하기 어렵다.

특히 XML이나 대용량 JSON을 반환하는 API라면 더 그렇다.

이럴 때는 결과를 파일로 저장할 수 있다.

 

curl -o result.json https://example.com/api/test

 

XML이라면:

 

curl -o result.xml https://example.com/api/test

 

저장 후 파일 크기도 확인할 수 있다.

Linux라면:

 

ls -lh result.xml

 

예를 들어:

-rw-r--r-- 1 user user 850M Sep 21 10:20 result.xml

 

처럼 보인다면 API 응답이 얼마나 큰지도 바로 확인할 수 있다.

대용량 API 문제를 확인할 때 꽤 유용하다.

---

다운로드 진행 상황도 확인할 수 있다

기본 curl에서는 파일을 내려받는 동안 진행 상태가 표시된다.

% Total    % Received % Xferd  Average Speed   Time
100  125M  100  125M    0     0   15.2M      0:00:08

 

여기서 응답이 중간에 멈춘다면 실제로 어느 정도까지 데이터를 받았는지도 확인할 수 있다.

특히:

curl: (18) transfer closed with outstanding read data remaining

 

처럼 오류가 발생한다면 HTTP 연결 자체는 됐지만 응답을 전부 받기 전에 연결이 종료된 상황을 의심해볼 수 있다.

---

요청 헤더를 추가하려면 -H

API에 따라 특정 Header가 필요한 경우도 있다.

이럴 때는 -H 옵션을 사용한다.

 

curl \
  -H "Accept: application/json" \
  https://example.com/api/test

 

여러 개를 넣을 수도 있다.

 

curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://example.com/api/test

 

실제 인증키나 토큰이 포함된 화면을 블로그에 올릴 때는 반드시 가려야 한다.

Authorization: Bearer ********

 

처럼 처리하는 게 좋다.

---

POST 요청을 보내려면?

GET뿐 아니라 POST API도 테스트할 수 있다.

예를 들어 JSON 데이터를 보내는 API라면:

 

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"test","value":"123"}' \
  https://example.com/api/test

 

-d 옵션을 사용하면 요청 Body에 데이터를 넣을 수 있다.

다만 -d를 사용하면 curl이 기본적으로 POST 요청을 사용하기 때문에 이런 경우 -X POST를 생략해도 된다.

 

curl \
  -H "Content-Type: application/json" \
  -d '{"name":"test","value":"123"}' \
  https://example.com/api/test

 

처음에는 POST = 무조건 -X POST라고 생각하기 쉬운데 curl이 다른 옵션을 통해 요청 방식을 결정하는 경우도 있다.

---

자주 사용하는 옵션만 정리하면

내가 API를 확인하는 정도라면 일단 이것들부터 알아두면 충분했다.

 

옵션	용도
curl URL	기본 요청
-i	응답 헤더 + 본문 확인
-I	HEAD 요청으로 헤더 확인
-v	연결 및 요청/응답 과정 자세히 확인
-o 파일명	응답을 파일로 저장
-H	요청 Header 추가
-d	요청 Body 데이터 전송
-X	요청 Method 직접 지정

전부 외우기보다는 상황에 따라 하나씩 붙여보면 된다.

내가 실제로 문제 확인할 때 많이 사용하는 형태는 오히려 단순하다.

 

curl -v "API_URL"

 

그리고 응답이 크다면:

 

curl -v -o result.xml "API_URL"

 

정도다.

---

브라우저에서 안 되면 curl도 확인해보자

API가 안 된다고 해서 바로 애플리케이션 코드 문제라고 단정하기는 어렵다.

예를 들어:

브라우저
    ↓
API 실패

 

만 확인했다면 원인이 JavaScript인지, 브라우저 정책인지, 네트워크인지, 서버인지 아직 알기 어렵다.

서버에서도 직접:

 

curl -v API_URL

 

을 실행해보면:

브라우저 실패
+
서버 curl 성공

 

인지,

브라우저 실패
+
서버 curl 실패

 

인지 구분할 수 있다.

여기에 다른 서버에서도 같은 요청을 해보면 범위를 더 좁힐 수 있다.

개발서버     실패
다른 서버    성공
내 PC        성공

 

이라면 API 자체보다는 특정 서버의 네트워크 경로나 보안정책 등을 확인해볼 근거가 생긴다.

API 장애를 볼 때 curl 하나만으로 원인을 확정할 수는 없지만 어디까지 정상이고 어디서부터 문제가 발생하는지 확인하는 도구로는 꽤 유용했다.

 

HTTP HTTPS 응답비교 예시

---

정리

처음에는 curl을 단순히 URL 한 번 호출해보는 명령어 정도로 사용했다.

그런데 API 문제가 생기면서 -v, -i, -o 같은 옵션을 같이 사용하다 보니 생각보다 확인할 수 있는 정보가 많았다.

특히 기억해둘 만한 건 이 정도다.

 

# 기본 호출
curl URL

# 응답 헤더 + 본문
curl -i URL

# 통신 과정 자세히
curl -v URL

# 결과 파일 저장
curl -o result.xml URL

# 통신 과정 확인 + 파일 저장
curl -v -o result.xml URL

 

그리고 API 문제를 확인할 때는 200 OK가 나왔는지만 보지 말고 응답 데이터가 끝까지 정상적으로 전달됐는지도 확인하는 것이 중요했다.

브라우저에서만 보던 오류를 서버에서 직접 확인해보면 생각보다 문제의 범위를 좁히기 쉬워진다.