cURL GET, POST, PUT, DELETE: 완벽 가이드 (2026)

cURL GET, POST, PUT, DELETE: 2026년 완전 가이드

cURL은 HTTP 요청을 보내기 위한 범용 명령줄 도구입니다. macOS와 대부분의 Linux 배포판에 기본적으로 설치되어 있으며, Windows에서도 쉽게 사용할 수 있습니다. API 테스트, 웹훅 디버깅, 스크립트 내 요청 자동화 등 어떤 작업을 하든 cURL은 유능한 개발자가 가장 먼저 찾는 도구입니다.

이 가이드는 실무에서 사용하게 될 모든 HTTP 메서드인 GET, POST, PUT, PATCH, DELETE를 다룹니다. 실제 사례, 자주 사용되는 플래그, 그리고 터미널에 바로 복사하여 사용할 수 있는 패턴을 함께 소개합니다.

빠른 참조 표

메서드	cURL 플래그	목적	본문(Body) 유무
GET	기본값 (플래그 필요 없음)	데이터 조회	없음
POST	-X POST 또는 --data	데이터 생성	있음
PUT	-X PUT	데이터 교체	있음
PATCH	-X PATCH	데이터 일부 수정	있음
DELETE	-X DELETE	데이터 삭제	드물게 있음
HEAD	-I 또는 -X HEAD	헤더 정보만 조회	없음
OPTIONS	-X OPTIONS	허용된 메서드 확인	없음

필수 cURL 플래그

예제를 살펴보기 전에, 자주 사용하게 될 플래그들을 정리했습니다:

# 일반적인 플래그
-X METHOD          # HTTP 메서드 지정 (POST, PUT, DELETE 등)
-H "Header: Value" # 요청 헤더 추가
-d "data"          # 요청 본문(body) 데이터 전송
-i                 # 출력에 응답 헤더 포함
-v                 # 세부 정보 표시 모드 (전체 요청/응답 확인)
-s                 # 자동 모드 (진행 바 숨기기)
-o filename        # 출력을 파일로 저장
-L                 # 리다이렉트 따라가기
-k                 # 안전하지 않은 SSL 연결 허용
-u user:pass       # 기본 인증(Basic authentication)
-b "cookies"       # 쿠키 전송
-c cookie-file     # 쿠키를 파일로 저장
--max-time 30      # 30초 후 타임아웃

GET 요청

GET은 기본 메서드입니다. -X GET을 명시할 필요가 없습니다.

기본 GET:

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

응답 헤더를 포함한 GET:

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

사용자 정의 헤더를 포함한 GET:

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

쿼리 매개변수를 포함한 GET:

# 옵션 1: URL에 포함
curl "https://api.example.com/search?q=hello&page=1&limit=10"

# 옵션 2: -G 플래그와 --data-urlencode 사용
curl -G \
  --data-urlencode "q=hello world" \
  --data-urlencode "page=1" \
  https://api.example.com/search

GET 요청 후 응답을 파일로 저장:

curl -o response.json https://api.example.com/data

상세 출력을 포함한 GET (디버깅에 용이):

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

# 출력 내용:
# > GET /health HTTP/2
# > Host: api.example.com
# > User-Agent: curl/8.x
# >
# < HTTP/2 200
# < content-type: application/json
# < ...

POST 요청

POST는 새로운 리소스를 생성하거나 데이터를 제출할 때 사용됩니다.

JSON 본문을 포함한 POST:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "alice@example.com",
    "role": "developer"
  }'

폼 데이터를 포함한 POST:

curl -X POST https://api.example.com/login \
  -d "username=alice&password=secret123"

참고: -d를 사용하면 cURL은 별도로 지정하지 않는 한 자동으로 Content-Type: application/x-www-form-urlencoded를 설정합니다.

파일의 데이터를 사용한 POST:

# 파일에서 JSON 읽기
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @payload.json

# 표준 입력(stdin)에서 읽기
echo '{"name": "Bob"}' | curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @-

파일 업로드를 포함한 POST (multipart form):

curl -X POST https://api.example.com/upload \
  -F "file=@photo.jpg" \
  -F "description=Profile photo" \
  -F "userId=123"

여러 파일을 포함한 POST:

curl -X POST https://api.example.com/upload \
  -F "files=@image1.jpg" \
  -F "files=@image2.png" \
  -F "files=@document.pdf"

PUT 요청

PUT은 리소스 전체를 대체합니다. 요청 본문에는 업데이트된 전체 리소스 정보가 포함되어야 합니다.

Resource를 업데이트하기 위한 PUT:

curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Updated",
    "email": "alice.new@example.com",
    "role": "senior-developer"
  }'

인증을 포함한 PUT:

curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -d '{
    "name": "Alice Updated",
    "email": "alice.new@example.com",
    "role": "senior-developer"
  }'

PATCH 요청

PATCH는 리소스 전체를 교체하지 않고 특정 필드만 업데이트합니다.

특정 필드 업데이트를 위한 PATCH:

curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{
    "role": "tech-lead"
  }'

PUT vs PATCH 비교:

# PUT: 리소스 전체를 보내야 함
curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "alice@example.com",
    "role": "tech-lead",
    "department": "engineering"
  }'

# PATCH: 변경하려는 부분만 보냄
curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{"role": "tech-lead"}'

DELETE 요청

DELETE는 리소스를 제거합니다. 대부분의 DELETE 요청은 본문을 필요로 하지 않습니다.

단순 DELETE:

curl -X DELETE https://api.example.com/users/42

인증을 포함한 DELETE:

curl -X DELETE https://api.example.com/users/42 \
  -H "Authorization: Bearer YOUR_TOKEN"

요청 본문을 포함한 DELETE (드문 경우):

curl -X DELETE https://api.example.com/users/batch \
  -H "Content-Type: application/json" \
  -d '{"ids": [42, 43, 44]}'

DELETE 요청 후 응답 코드 확인:

# -w는 HTTP 상태 코드를 표시하고, -o /dev/null은 본문을 숨김
curl -X DELETE https://api.example.com/users/42 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o /dev/null \
  -w "HTTP Status: %{http_code}\n" \
  -s

인증 패턴

Bearer Token (API에서 가장 흔히 사용됨):

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.example.com/protected

기본 인증 (Basic Auth):

# 옵션 1: -u 플래그 사용
curl -u username:password https://api.example.com/data

# 옵션 2: 헤더 사용 (base64 인코딩)
curl -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  https://api.example.com/data

헤더에 API 키 포함:

curl -H "X-API-Key: your-api-key-here" \
  https://api.example.com/data

쿼리 매개변수에 API 키 포함:

curl "https://api.example.com/data?api_key=your-api-key-here"

실전 API 예제

GitHub API

# 리포지토리 목록 조회
curl -H "Authorization: Bearer ghp_YOUR_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/user/repos

# 새 리포지토리 생성
curl -X POST https://api.github.com/user/repos \
  -H "Authorization: Bearer ghp_YOUR_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  -d '{
    "name": "my-new-repo",
    "private": true,
    "description": "Created via cURL"
  }'

OpenAI API

curl -X POST https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ],
    "max_tokens": 100
  }'

Stripe API

# 고객(Customer) 생성
curl -X POST https://api.stripe.com/v1/customers \
  -u sk_test_YOUR_KEY: \
  -d "email=customer@example.com" \
  -d "name=Jane Doe"

고급 패턴

bash 루프를 이용한 실패 시 재시도:

MAX_RETRIES=3
RETRY_COUNT=0

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" https://api.example.com/data)

  if [ "$HTTP_CODE" -eq 200 ]; then
    echo "Success"
    curl -s https://api.example.com/data
    break
  fi

  RETRY_COUNT=$((RETRY_COUNT + 1))
  echo "Attempt $RETRY_COUNT failed with $HTTP_CODE. Retrying..."
  sleep $((RETRY_COUNT * 2))
done

응답 시간 측정:

curl -o /dev/null -s -w "
  DNS Lookup:  %{time_namelookup}s
  Connect:     %{time_connect}s
  TLS Setup:   %{time_appconnect}s
  First Byte:  %{time_starttransfer}s
  Total Time:  %{time_total}s
  HTTP Code:   %{http_code}
" https://api.example.com/health

병렬로 요청 보내기:

# xargs를 사용한 병렬 요청
seq 1 10 | xargs -P 5 -I {} curl -s "https://api.example.com/item/{}"

흔히 발생하는 문제와 해결법

문제	원인	해결 방법
curl: (60) SSL certificate problem	자체 서명된 인증서	-k 플래그 추가 (개발용으로만 권장)
JSON이 전송되지 않음	Content-Type 헤더 누락	-H "Content-Type: application/json" 추가
데이터에 특수문자 포함	셸(Shell) 해석 오류	작은따옴표 사용 또는 이스케이프 처리
응답이 비어 있음	서버가 204를 반환	-i를 사용하여 상태 코드 확인
curl: (7) Failed to connect	잘못된 포트 또는 호스트	URL 및 포트 번호 확인

마무리하며

cURL은 API를 다루는 개발자에게 없어서는 안 될 도구입니다. 이 가이드에 소개된 패턴들은 단순한 GET 요청부터 파일 업로드를 포함한 인증된 POST 호출까지, 대부분의 실제 사례를 다루고 있습니다.

이미지 생성, 비디오 제작, 음성 합성 등 AI API를 연동하는 애플리케이션을 개발하고 있다면, cURL은 코드에 통합하기 전 API 호출을 프로토타이핑하고 테스트하기 위한 훌륭한 방법입니다. Hypereal AI는 수십 개의 AI 모델에 대한 RESTful API 엔드포인트를 제공하며, 모든 엔드포인트는 위에서 설명한 cURL 패턴과 완벽하게 호환됩니다.