GET
POST
PUT / PATCH
DELETE
Bearer Auth
File Upload
기본 문법 구조
curl의 기본 구조는 아래와 같습니다. 옵션 순서는 대부분 상관없으나, URL은 옵션 없이 단독으로 쓰거나 마지막에 위치시키는 것이 관례입니다.
curl
[옵션]
[URL]
# 예시
curl
-X POST
-H "Content-Type: application/json"
-d '{"name":"홍길동"}'
https://api.example.com/users
curl 이란?
- Client URL의 약자. 터미널에서 HTTP 요청을 보내는 범용 도구입니다.
- API 테스트, 파일 다운로드, 서버 헬스 체크 등 다양한 용도로 사용합니다.
- FastAPI, Django, Spring 등 모든 서버와 통신 가능하며 macOS/Linux에 기본 내장되어 있습니다.
주요 옵션 목록
| 옵션 | 이름 | 설명 및 사용 예 |
|---|
| -X | 메서드 지정 | HTTP 메서드를 명시. 기본값은 GET. -X POST, -X DELETE |
| -H | 헤더 추가 | 요청 헤더를 추가. 여러 번 사용 가능. -H "Authorization: Bearer 토큰" |
| -d | 요청 바디 | POST/PUT 요청의 본문 데이터. -d '{"key":"value"}' |
| -F | 폼 데이터 | multipart/form-data 전송. 파일 업로드에 사용. -F "file=@photo.jpg" |
| -o | 파일 저장 | 응답을 파일로 저장. -o result.json |
| -O | 파일명 유지 | URL의 파일명 그대로 저장. -O https://.../file.zip |
| -i | 헤더 포함 출력 | 응답 헤더와 바디를 함께 출력 |
| -I | 헤더만 출력 | HEAD 요청. 응답 헤더만 출력 (바디 없음) |
| -v | 상세 출력 | 요청/응답 전체 과정을 출력. 디버깅에 유용 |
| -s | 조용히 실행 | 진행률 및 에러 메시지 숨김. 스크립트에서 활용 |
| -u | Basic Auth | 사용자명:비밀번호 형식. -u admin:1234 |
| -L | 리다이렉트 추적 | 301/302 리다이렉트를 자동으로 따라감 |
| -k | SSL 검증 생략 | 자체 서명 인증서 등 SSL 오류 무시 (개발용) |
| --max-time | 타임아웃 | 최대 대기 시간(초). --max-time 10 |
| -c / -b | 쿠키 | -c cookie.txt 저장, -b cookie.txt 전송 |
GET 요청
curl의 기본 메서드는 GET입니다. -X GET은 생략해도 동일하게 동작합니다.
URL에 직접 접근. 가장 기본적인 형태입니다.
$curl https://jsonplaceholder.typicode.com/posts/1
Response
{
"userId": 1,
"id": 1,
"title": "sunt aut facere...",
"body": "quia et suscipit..."
}
URL에 ?key=value 형식으로 검색 조건을 전달합니다.
$curl "https://jsonplaceholder.typicode.com/posts?userId=1&_limit=3"
# URL에 &가 있으면 반드시 따옴표로 감싸세요
Response
[ { "userId": 1, "id": 1, ... },
{ "userId": 1, "id": 2, ... },
{ "userId": 1, "id": 3, ... } ]
바디 없이 응답 헤더만 확인합니다. 서버 상태, Content-Type 점검에 유용합니다.
$curl -I https://jsonplaceholder.typicode.com/posts/1
Response Headers
200
application/json; charset=utf-8
max-age=43200
POST 요청
데이터를 서버로 전송할 때 사용합니다. -d로 JSON 바디를, -H로 Content-Type을 반드시 함께 지정합니다.
가장 일반적인 REST API POST 요청 형태입니다.
$curl -X POST \
-H "Content-Type: application/json" \
-d '{"title":"curl 가이드","body":"내용","userId":1}' \
https://jsonplaceholder.typicode.com/posts
Response 201 Created
{ "id": 101, "title": "curl 가이드", "body": "내용", "userId": 1 }
HTML form의 일반 submit과 동일한 방식입니다.
$curl -X POST \
-d "username=hong&password=1234" \
http://localhost:8000/login
Response
{ "access_token": "eyJhbGci...", "token_type": "bearer" }
PUT / PATCH 요청
PUT은 리소스 전체를 교체하고, PATCH는 일부 필드만 수정합니다.
id=1 게시글의 모든 필드를 새 값으로 교체합니다.
$curl -X PUT \
-H "Content-Type: application/json" \
-d '{"id":1,"title":"수정된 제목","body":"수정된 내용","userId":1}' \
https://jsonplaceholder.typicode.com/posts/1
Response 200 OK
{ "id": 1, "title": "수정된 제목", ... }
제목 하나만 변경합니다. 나머지 필드는 서버에서 기존 값을 유지합니다.
$curl -X PATCH \
-H "Content-Type: application/json" \
-d '{"title":"제목만 바꿈"}' \
https://jsonplaceholder.typicode.com/posts/1
Response 200 OK
{ "id": 1, "title": "제목만 바꿈", "body": "기존 내용 유지" }
DELETE 요청
리소스를 삭제합니다. 성공 시 보통 204 No Content 또는 빈 {}를 반환합니다.
id=1 게시글을 삭제합니다.
$curl -X DELETE https://jsonplaceholder.typicode.com/posts/1
# 응답 상태코드도 함께 보고 싶을 때
$curl -X DELETE -i https://jsonplaceholder.typicode.com/posts/1
파일 업로드
-F 옵션으로 multipart/form-data 방식의 파일 업로드를 할 수 있습니다. FastAPI의 UploadFile과 연동됩니다.
파일 경로 앞에 @를 붙이면 해당 파일을 읽어서 전송합니다.
$curl -X POST \
-F "file=@/Users/hong/photo.jpg" \
http://localhost:8000/upload
Response
{ "filename": "photo.jpg", "size": 204800, "url": "/files/photo.jpg" }
파일과 함께 텍스트 필드도 같이 전송할 수 있습니다.
$curl -X POST \
-F "file=@report.pdf" \
-F "title=2026년 보고서" \
-F "category=finance" \
http://localhost:8000/documents
Response
{ "id": 7, "title": "2026년 보고서", "category": "finance" }
디버깅 & 출력 제어
요청 헤더, 응답 헤더, 바디 전체를 모두 출력합니다. 오류 디버깅 시 필수입니다.
$curl -v http://localhost:8000/health
Verbose Output
* Trying 127.0.0.1:8000...
* Connected to localhost port 8000
>
> localhost:8000
< 200 OK
< application/json
{ "status": "ok" }
응답 JSON을 파일로 저장하거나, jq로 예쁘게 출력합니다.
$curl -s -o result.json http://localhost:8000/students
# jq로 예쁘게 출력 (jq 설치 필요)
$curl -s http://localhost:8000/students | jq .
jq 출력 결과
[
{ "id": 1, "name": "홍길동", "grade": 3 }
]
FastAPI 연동 실전 예제
실제 로컬 FastAPI 서버를 기준으로 한 curl 테스트 흐름입니다.
테스트 전 서버 확인
- FastAPI 실행:
uvicorn main:app --reload
- Swagger UI 접속: http://localhost:8000/docs
- curl로 헬스 체크:
curl http://localhost:8000/
FastAPI OAuth2 로그인부터 보호된 엔드포인트 호출까지 전체 흐름입니다.
# 1. 로그인 (토큰 획득)
$curl -X POST \
-d "username=teacher01&password=pass1234" \
http://localhost:8000/auth/token
# 2. 학생 목록 조회 (토큰 필요)
$curl \
-H "Authorization: Bearer <위에서받은토큰>" \
http://localhost:8000/students
# 3. 학생 등록 (POST + 토큰)
$curl -X POST \
-H "Authorization: Bearer <토큰>" \
-H "Content-Type: application/json" \
-d '{"name":"김철수","grade":2,"class_no":"3반"}' \
http://localhost:8000/students
Response 201 Created
{ "id": 58, "name": "김철수", "grade": 2, "class_no": "3반" }
✅ 자주 쓰는 패턴 요약
- GET 조회:
curl http://localhost:8000/items/1
- POST JSON:
curl -X POST -H "Content-Type: application/json" -d '{...}' URL
- 인증 포함:
curl -H "Authorization: Bearer 토큰" URL
- 파일 업로드:
curl -X POST -F "file=@파일경로" URL
- 디버깅:
curl -v URL 또는 응답만: curl -s URL | jq .
"curl은 API의 청진기다 — 서버가 살아있는지, 무슨 말을 하는지 직접 들어보자"