반응형

 

API를 테스트할 때 가장 빠른 방법은 curl입니다. 별도 도구 설치 없이 터미널에서 바로 GET, POST, 인증 요청까지 모두 처리할 수 있습니다.

 

이 글에서는 curl의 핵심 옵션과 실무에서 바로 쓸 수 있는 명령어를 정리했습니다. 모든 예제는 공개 테스트 API(jsonplaceholder.typicode.com)를 사용하므로 별도 서버 준비 없이 따라할 수 있습니다.

 

1. curl 설치 확인

 

curl은 macOS와 Linux에 기본 내장되어 있습니다. Windows 10 버전 이상도 기본 포함되어 있습니다.

 

아래 명령어로 설치 여부와 버전을 확인합니다.

 

# MacOS/Linux 시스템
curl --version

# Windows 시스템
curl.exe --version

 

버전 정보가 출력되면 정상입니다. curl이 없는 경우 curl 공식 사이트에서 설치할 수 있습니다.

Windows 시스템 - curl version 확인 명령어
MacOS 시스템 - curl version 확인 명령어

 

 

💡 Windows 사용자 주의: Windows cmd에서는 작은따옴표(') 대신 큰따옴표(")를 사용해야 합니다. 따라서 가급적이면 Git을 설치하여 Git Bash 또는 WSL를 사용한 테스트를 권장합니다.

 

2. curl 핵심 옵션 한눈에 보기

옵션 설명
-X HTTP 메서드 지정 (GET, POST, PUT, DELETE 등). 기본값은 GET
-H 요청 헤더 추가. 예: -H "Content-Type: application/json"
-d 요청 본문(body) 데이터 전송. POST/PUT 시 사용
-u Basic 인증. 예: -u username:password
-i 응답 헤더 + 본문 함께 출력
-I 응답 헤더만 출력 (본문 없음)
-v 요청/응답 전체 상세 출력. 디버깅에 유용
-s 진행 표시 없이 조용히 실행 (silent 모드)
-o 응답을 파일로 저장. 예: -o response.json
-L 301/302 리다이렉트를 자동으로 따라감
-k SSL 인증서 검증 무시 (개발 환경 전용)

 

3. GET 요청

curl의 기본 동작은 GET 요청입니다. URL만 입력하면 됩니다.

 

 

3-1. 기본 GET 요청

curl https://jsonplaceholder.typicode.com/posts/1

 

실행하면 아래와 같이 JSON 응답이 출력됩니다.

curl - 기본 get 요청 결과

 

 

3-2. 응답 헤더 함께 확인

API 응답의 Content-Type, 상태 코드 등 헤더 정보를 함께 확인하려면 -i 옵션을 사용합니다.

curl -i https://jsonplaceholder.typicode.com/posts/1

 

curl -i 옵션 명령어 결과

 

 

3-3. 쿼리 파라미터 포함

curl "https://jsonplaceholder.typicode.com/posts?userId=1"

💡 쿼리 파라미터가 포함된 URL은 따옴표로 감싸는 것이 안전합니다. & 문자가 셸에서 특수하게 해석될 수 있기 때문입니다.

 

 

3-4. 요청/응답 전체 흐름 디버깅

curl -v https://jsonplaceholder.typicode.com/posts/1

 

-v 옵션은 TCP 연결, 요청 헤더, 응답 헤더, 응답 본문 전체를 출력합니다. API가 예상대로 동작하지 않을 때 가장 먼저 사용하는 옵션입니다.

cur -v 옵션 명령어 결과

 

 

4. POST 요청

 

4-1. JSON 데이터 전송

JSON을 POST로 전송할 때는 서버가 본문을 JSON으로 해석할 수 있도록 Content-Type: application/json 헤더를 함께 지정하는 것이 권장됩니다.

실제 업무 API 처럼 인증이 필요한 경우에는 Authorization: Bearer {API_KEY}를 함께 지정합니다.

 

 

macOS / Linux

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{"title": "테스트 제목", "body": "테스트 내용", "userId": 1}'

 

 

Windows (cmd)

curl.exe -X POST https://jsonplaceholder.typicode.com/posts ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ^
  -d "{\"title\": \"테스트 제목\", \"body\": \"테스트 내용\", \"userId\": 1}"

 

성공 시 HTTP 201 상태 코드와 함께 생성된 리소스가 응답됩니다.

 

 

 

4-2. JSON 파일을 본문으로 전송

데이터가 길거나 복잡할 때는 JSON 파일을 만들어서 전송하는 것이 편리합니다.

먼저 data.json 파일을 생성합니다.

 

# data.json 파일 내용

{
  "title": "파일로 전송하는 POST",
  "body": "data.json 파일 내용",
  "userId": 1
}

 

파일 앞에 @를 붙여서 전송합니다.

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d @data.json

 

 

4-3. Form 데이터 전송

HTML 폼 전송 방식(application/x-www-form-urlencoded)으로 보낼 때는 -d를 그대로 사용합니다. POST의 기본 Content-Type이 이 형식입니다.

curl -X POST https://httpbin.org/post \
  -d "username=admin&password=1234"

 

5. PUT / PATCH / DELETE 요청

 

5-1. PUT - 리소스 전체 수정

# macOS / Linux
curl -X PUT https://jsonplaceholder.typicode.com/posts/1 \
  -H "Content-Type: application/json" \
  -d '{"id": 1, "title": "수정된 제목", "body": "수정된 내용", "userId": 1}'

 

 

5-2. PATCH - 리소스 일부 수정

# macOS / Linux
curl -X PATCH https://jsonplaceholder.typicode.com/posts/1 \
  -H "Content-Type: application/json" \
  -d '{"title": "제목만 수정"}'

 

 

5-3. DELETE - 리소스 삭제

curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

 

성공 시 HTTP 200과 함께 빈 JSON {}이 반환됩니다.

 

6. 인증 (Authentication)

 

6-1. Basic 인증

사용자명과 비밀번호를 -u 옵션으로 전달합니다. curl이 내부적으로 Base64 인코딩해서 Authorization: Basic 헤더로 변환합니다.

curl -u username:password https://api.example.com/protected

 

비밀번호를 터미널에 노출하지 않으려면 사용자명만 입력하고 엔터를 누르면 비밀번호를 숨김 입력으로 받습니다.

curl -u username https://api.example.com/protected
# Enter host password for user 'username': (입력 숨김)

 

 

6-2. Bearer 토큰 인증 (JWT, OAuth2)

가장 많이 사용하는 인증 방식입니다. -H 옵션으로 Authorization 헤더를 직접 지정합니다.

# macOS / Linux
curl -X GET https://api.example.com/user/me \
  -H "Authorization: Bearer abcdefghijklmnopqrstuvwxyzabced..."

 

# Windows (cmd)
curl -X GET https://api.example.com/user/me ^
  -H "Authorization: Bearer abcdefghijklmnopqrstuvwxyzabced......"

 

 

6-3. API Key 인증

API Key는 서비스마다 전달 방식이 다릅니다. 헤더로 전달하거나 쿼리 파라미터로 전달하는 두 가지 방식이 일반적입니다.

# 헤더로 전달
curl -X GET https://api.example.com/data \
  -H "X-API-Key: your-api-key-here"

# 쿼리 파라미터로 전달
curl "https://api.example.com/data?api_key=your-api-key-here"

 

7. 실무에서 자주 쓰는 패턴

 

7-1. HTTP 상태 코드만 빠르게 확인

서버 정상 동작 여부를 빠르게 점검할 때 유용합니다. 본문 없이 상태 코드만 출력합니다.

curl -s -o /dev/null -w "%{http_code}" https://jsonplaceholder.typicode.com/posts/1
# 출력: 200

 

Linux - curl 상태코드 출력 결과

 

 

Windows에서는 /dev/null 대신 NUL을 사용합니다.

# Windows (cmd)
curl -s -o NUL -w "%{http_code}" https://jsonplaceholder.typicode.com/posts/1

 

Windows - curl 상태코드 출력 결과

 

7-2. 응답을 파일로 저장

curl -s https://jsonplaceholder.typicode.com/posts -o posts.json

 

 

7-3. SSL 인증서 무시 (개발 환경 전용)

자체 서명 인증서를 사용하는 개발 서버에서 SSL 오류가 발생할 때 사용합니다. 운영 환경에서는 절대 사용하지 마세요.

curl -k https://localhost:8443/api/test

 

 

7-4. 요청과 응답을 한 번에 보기 (보안 엔지니어 추천)

API가 어떤 헤더를 주고받는지 전체를 확인할 때 유용합니다. 보안 점검 시 자주 사용하는 패턴입니다.

curl -v -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-token-123" \
  -d '{"title": "보안 헤더 확인", "userId": 1}'

 

-v 출력에서 >로 시작하는 줄이 요청, <로 시작하는 줄이 응답입니다.

Git Bash를 이용한 curl 명령어

 

8. 자주 발생하는 에러와 해결 방법

에러 메시지 원인 및 해결 방법
curl: (6) Could not resolve host DNS 오류 또는 URL 오타 → URL 주소 확인, 네트워크 연결 확인
curl: (7) Failed to connect 서버가 실행 중이지 않거나 포트 오류 → 서버 상태 및 포트 확인
curl: (60) SSL certificate problem SSL 인증서 오류 → 개발 환경이면 -k 추가, 운영 환경이면 인증서 갱신
HTTP 415 Unsupported Media Type Content-Type 헤더 누락 → -H "Content-Type: application/json" 추가
HTTP 401 Unauthorized 인증 정보 없거나 만료 → Authorization 헤더 또는 -u 옵션 확인
Windows에서 JSON 파싱 오류 작은따옴표(') 사용 → 큰따옴표(")로 변경하고 내부 따옴표는 \"로 이스케이프

 

9. curl 명령어 치트시트

# GET 기본
curl https://api.example.com/resource

# GET 응답 헤더 포함
curl -i https://api.example.com/resource

# GET 상세 디버깅
curl -v https://api.example.com/resource

# POST JSON
curl -X POST https://api.example.com/resource \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# POST JSON 파일
curl -X POST https://api.example.com/resource \
  -H "Content-Type: application/json" \
  -d @data.json

# PUT
curl -X PUT https://api.example.com/resource/1 \
  -H "Content-Type: application/json" \
  -d '{"key": "updated"}'

# PATCH
curl -X PATCH https://api.example.com/resource/1 \
  -H "Content-Type: application/json" \
  -d '{"key": "patched"}'

# DELETE
curl -X DELETE https://api.example.com/resource/1

# Basic 인증
curl -u username:password https://api.example.com/protected

# Bearer 토큰 인증
curl -H "Authorization: Bearer TOKEN" https://api.example.com/protected

# API Key (헤더)
curl -H "X-API-Key: YOUR_KEY" https://api.example.com/data

# 상태 코드만 출력
curl -s -o /dev/null -w "%{http_code}" https://api.example.com/resource

# 응답 파일 저장
curl -s https://api.example.com/resource -o output.json

# SSL 무시 (개발 전용)
curl -k https://localhost:8443/api/test

 

공식 출처

 

기술 문서 및 전문가 참고

  • Dale Seo, "curl 커맨드로 터미널에서 HTTP 호출하기": daleseo.com/curl
  • 박연오, "커맨드라인 환경에서 REST API 요청 보내기": bakyeono.net

 

 

다음 포스팅에서는 Postman으로 API 테스트하는 방법 - 설치부터 컬렉션 관리까지 가이드를 다뤄볼 예정입니다. GUI 환경에서 더 편리하게 API를 테스트하고 싶다면 참고해 주세요.

 

 

내용이 유용하셨다면 좋아요&댓글 부탁드립니다.
이 블로그를 이끌어갈 수 있는 강력한 힘입니다!

반응형
저작자표시 비영리 변경금지 (새창열림)

'IT > General' 카테고리의 다른 글

Postman으로 API 테스트하는 방법 - 설치부터 컬렉션 관리까지 가이드  (0) 2026.05.09
안전보건교육 휴넷 자동 스킵 방법 — JavaScript로 간단히 해결  (1) 2025.06.10
Elasticsearch Result window is too large 에러 원인과 해결 방법  (0) 2025.01.08
Visual Studio 빌드 오류 "마지막으로 성공한 빌드 실행" 해결 방법  (0) 2024.12.17
Windows OpenJDK 설치 방법 — JDK 버전별 설치 및 환경변수 설정  (0) 2024.12.03

+ Recent posts

티스토리툴바