curl을 이용한 HTTP method 실습

1. 실습 목적

curl을 이용하여 REST API 등에

• HTTP request를 보내고,
• 각 HTTP method의 차이를 확인.

실습할 HTTP method는 다음과 같음:

HTTP method	의미	딥러닝 모델 서비스의 예
GET	리소스 조회	저장된 추론 결과 조회
POST	리소스 생성 또는 처리 요청	이미지를 입력하여 추론 수행
PUT	리소스 전체 교체	추론 결과 정보를 전체 수정
PATCH	리소스 일부 수정	검토 여부만 수정
DELETE	리소스 삭제	저장된 추론 결과 삭제
HEAD	response body 없이 header만 조회	리소스의 존재 여부 확인
OPTIONS	사용할 수 있는 method 확인	API가 지원하는 method 확인

2026.07.28 - [WebApp] - HTTP method

HTTP method

2026.07.28 - [WebApp] - REST API

REST API

---

2. curl이란?

curl은 URL을 이용하여 서버에 request를 보내는 명령행 도구임.

 

웹 브라우저를 사용하지 않고도 REST API를 직접 호출할 수 있기 때문에 API 개발과 테스트에 자주 사용됨.

 

기본 형식은 다음과 같음:

curl [option] URL

설치 여부는 다음 명령으로 확인 가능:

curl --version

 

2023.09.29 - [utils] - [Util] curl 간단사용법 정리 : web의 자원 다운로드하기.

[Util] curl 간단사용법 정리 : web의 자원 다운로드하기.

---

3. 실습용 서버

이 문서에선 실습에서는 다음 서버를 사용하겠음.

https://httpbin.org

httpbin은 클라이언트가 보낸 HTTP request를 JSON 형식으로 다시 보여주는 테스트 서버임.

 

다음 URL을 기본 리소스 주소로 사용한다:

https://httpbin.org/anything/inference-results/101

 

이 주소는 다음과 같은 REST API를 가정한 것임:

/inference-results/101

• 의미는 101번 추론 결과 임.

다만 httpbin은 요청 내용을 확인하기 위한 테스트 서버임에 유의할 것:

• 즉, POST, PUT, PATCH, DELETE를 실행하더라도
• 이들은 실제 데이터베이스의 내용이 변경되지는 않음.

---

4. GET request

GET은 서버에 저장된 리소스를 조회할 때 사용됨.

4.1 기본 GET

curl "https://httpbin.org/anything/inference-results/101"

• curl에서 별도의 method를 지정하지 않으면 기본적으로 GET을 사용.

응답에서 다음 부분을 확인할 수 있음:

{
  "method": "GET",
  "url": "https://httpbin.org/anything/inference-results/101"
}

 

이 요청의 의미는 다음과 같음:

101번 추론 결과를 조회한다.

 

명시적으로 GET을 지정할 수도 있음:

curl -X GET "https://httpbin.org/anything/inference-results/101"

 

그러나 GET은 기본 method이므로 일반적으로 -X GET은 생략하여 사용됨.

---

4.2 Query parameter를 이용한 조회

조회 조건은 URL 뒤에 query parameter로 전달할 수 있음:

curl "https://httpbin.org/anything/inference-results?class=cancer&limit=5"

 

다음과 같이 응답에서 args를 확인할 수 있음:

{
  "args": {
    "class": "cancer",
    "limit": "5"
  }
}

 

이 요청은 다음과 같이 해석할 수 있음:

class가 cancer인 추론 결과를 최대 5개 조회한다.

 

Query parameter는 ? 뒤에 작성하고, 여러 개를 전달할 때는 &로 구분한다.

?class=cancer&limit=5

 

URL에 &가 들어가는 경우에는 URL 전체를 따옴표로 감싸는 것이 안전함.

---

5. POST request

POST는 새로운 리소스를 생성하거나 서버에 처리를 요청할 때 사용됨.

 

딥러닝 모델 서비스에서는 이미지를 입력하여 새로운 추론 결과를 생성할 때 사용할 수 있음:

curl -X POST \
  "https://httpbin.org/anything/inference-results" \
  -H "Content-Type: application/json" \
  -d '{"image":"tongue_001.jpg","model":"vit"}'

 

한 줄로 작성하면 다음과 같음:

curl -X POST "https://httpbin.org/anything/inference-results" -H "Content-Type: application/json" -d '{"image":"tongue_001.jpg","model":"vit"}'

 

각 option의 의미는 다음과 같음.

Option	의미
-X POST	HTTP method를 POST로 지정
-H	request header 추가
Content-Type: application/json	request body가 JSON 형식임을 표시
-d	request body에 포함할 데이터

 

응답에서 다음 내용을 확인 가능함:

{
  "json": {
    "image": "tongue_001.jpg",
    "model": "vit"
  },
  "method": "POST"
}

 

이 요청의 의미는 다음과 같음:

tongue_001.jpg를 vit 모델에 입력하여 새로운 추론 결과를 생성한다.

• -d를 사용하면 curl은 기본적으로 POST를 선택함.
• 따라서 다음과 같이 -X POST를 생략할 수도 있음.

curl \
  "https://httpbin.org/anything/inference-results" \
  -H "Content-Type: application/json" \
  -d '{"image":"tongue_001.jpg","model":"vit"}'

• method를 명확하게 확인하기 위해
• -X POST를 작성하는 편을 권함.

---

6. PUT request

PUT은 기존 리소스의 전체 내용을 새로운 내용으로 교체할 때 사용함:

curl -X PUT \
  "https://httpbin.org/anything/inference-results/101" \
  -H "Content-Type: application/json" \
  -d '{"id":101,"image":"tongue_001.jpg","label":"cancer","reviewed":true}'

 

다음과 같이 응답에서는 method와 json을 확인 가능함:

{
  "method": "PUT",
  "json": {
    "id": 101,
    "image": "tongue_001.jpg",
    "label": "cancer",
    "reviewed": true
  }
}

 

이 요청의 의미는 다음과 같음:

101번 추론 결과의 전체 정보를 전달한 내용으로 교체한다.

• PUT에서는 일반적으로
• 리소스를 구성하는 전체 내용을 전달함.
• 전면 교체이기 때문에...

 

예를 들어 reviewed 값 하나만 변경하더라도 다음과 같이 전체 리소스를 다시 전달하는 방식임.

{
  "id": 101,
  "image": "tongue_001.jpg",
  "label": "cancer",
  "reviewed": true
}

---

7. PATCH request

PATCH는 기존 리소스의 일부 내용만 수정할 때 사용함:

curl -X PATCH \
  "https://httpbin.org/anything/inference-results/101" \
  -H "Content-Type: application/json" \
  -d '{"reviewed":true}'

 

응답은 다음과 같은 형태임:

{
  "method": "PATCH",
  "json": {
    "reviewed": true
  }
}

 

이 요청의 의미는 다음과 같음:

101번 추론 결과에서 reviewed 값만 true로 수정한다.

 

PUT과 PATCH의 차이는 다음과 같음:

PUT   : 리소스 전체를 전달하여 교체
PATCH : 변경할 일부 필드만 전달하여 수정

 

예를 들어 기존 리소스가 다음과 같다고 가정:

{
  "id": 101,
  "image": "tongue_001.jpg",
  "label": "cancer",
  "reviewed": false
}

 

reviewed만 변경하려면 PATCH에서는 다음 값만 전달하면 됨:

{
  "reviewed": true
}

---

8. DELETE request

DELETE는 서버에 저장된 리소스를 삭제할 때 사용:

curl -X DELETE \
  "https://httpbin.org/anything/inference-results/101"

 

응답에서 다음 내용을 확인할 수 있음:

{
  "method": "DELETE"
}

 

이 요청의 의미는 다음과 같음:

101번 추론 결과를 삭제한다.

 

실제 REST API에서 삭제가 성공하면 다음과 같은 status code가 반환될 수 있음:

200 OK
204 No Content

 

204 No Content는 요청은 성공했지만 response body는 없다는 의미임.

---

9. HEAD request

HEAD는 GET과 유사하지만 response body는 받지 않고 response header만 확인 가능함:

curl -I "https://httpbin.org/anything/inference-results/101"

 

출력은 다음과 같은 형태임:

HTTP/2 200
content-type: application/json
content-length: 420
server: gunicorn

 

HEAD는 다음과 같은 경우에 사용할 수 있음:

리소스가 존재하는지 확인
Content-Type 확인
Content-Length 확인
캐시 관련 header 확인
파일을 실제로 내려받지 않고 정보만 확인

 

HEAD request에서는 다음과 같이 -I를 사용하는 것이 일반적임:

curl -I URL

• -X HEAD를 사용할 수도 있지만,
• curl이 response body를 기다리는 방식에 차이가 생길 수 있으므로
• -I를 사용하는 편이 권장됨.

---

10. OPTIONS request

OPTIONS는 대상 URL에서 사용할 수 있는 HTTP method나 통신 기능을 확인할 때 사용됨:

curl -i -X OPTIONS \
  "https://httpbin.org/anything/inference-results/101"

 

응답에서 다음과 같이 OPTIONS request가 전달된 것을 확인할 수 있음:

{
  "method": "OPTIONS"
}

 

실제 REST API에서는 다음과 같은 response header가 반환될 수 있음.

Allow: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

• 이는 해당 리소스에서 사용할 수 있는 HTTP method를 의미함..

주의한 점은

• 모든 서버가 OPTIONS에 동일한 형식으로 응답하는 것은 아님.
• 서버 설정에 따라 Allow header가 반환되지 않을 수도 있음.

---

11. Response header 확인

기본 curl 명령은 response body 만을 출력함.

• Response header와 body를 함께 확인하려면
• -i를 사용.

curl -i "https://httpbin.org/get"

 

출력은 다음과 같은 구조임:

HTTP/2 200
content-type: application/json
content-length: 256

{
  "args": {},
  "headers": {}
}

 

Header와 body 사이에는 빈 줄이 있음:

HTTP response header

HTTP response body

---

12. HTTP 통신 과정 확인

Request와 response의 상세한 통신 과정을 확인하려면 -v를 사용하면 됨:

curl -v "https://httpbin.org/get"

• -v는 verbose의 약자이다.

 

출력에서 기호의 의미는 다음과 같음:

> 클라이언트가 서버에 보낸 내용
< 서버가 클라이언트에 보낸 내용
* curl이 출력한 연결 상태

 

예를 들어 다음 부분은 curl이 서버에 보낸 request 임:

> GET /get HTTP/1.1
> Host: httpbin.org
> User-Agent: curl/...

 

다음 부분은 서버가 반환한 response 임

< HTTP/1.1 200 OK
< Content-Type: application/json

 

다음과 같이 *로 시작하는 줄은 HTTP request나 response가 아니라 curl 자체의 상태 메시지 임:

* Connection #0 to host httpbin.org:443 left intact

 

이는 다음을 의미:

httpbin.org의 HTTPS 포트인 443번 포트와 통신을 마쳤고,
해당 연결을 재사용할 수 있는 상태로 유지하였다.

---

13. Request header 전달

-H option을 사용하면 HTTP request header를 추가할 수 있음:

curl \
  "https://httpbin.org/anything/inference-results/101" \
  -H "Accept: application/json" \
  -H "X-Client-Name: oral-lesion-app"

• -H는 여러 번 사용할 수 있음.

httpbin에서의 응답의 headers에서 전달한 값으로 확인 가능함.

{
  "headers": {
    "Accept": "application/json",
    "X-Client-Name": "oral-lesion-app"
  }
}

---

14. Bearer token 전달

실제 REST API에서는 사용자가 API를 호출할 권한이 있는지 확인하기 위해 access token을 사용하는 경우가 많음.

 

Bearer token은 일반적으로 다음 header에 포함됨.

Authorization: Bearer ACCESS_TOKEN

 

각 부분의 의미는 다음과 같음:

부분	의미
Authorization	인증 정보를 전달하는 header 이름
Bearer	token을 이용하는 인증 방식
ACCESS_TOKEN	인증 서버가 발급한 실제 token 문자열

 

Bearer와 token 사이에는 공백 한 칸이 필요하다.

Authorization: Bearer 실제_token

---

14.1 실습용 token

httpbin 실습에서는 다음과 같은 임의의 문자열을 사용할 수 있음:

example-token-123

이 값을 header에 넣으면 다음과 같음:

curl \
  "https://httpbin.org/anything/inference-results/101" \
  -H "Authorization: Bearer example-token-123"

한 줄로 작성하면 다음과 같음:

curl "https://httpbin.org/anything/inference-results/101" -H "Authorization: Bearer example-token-123"

응답의 headers에서 다음 값을 확인할 수 있음:

{
  "headers": {
    "Authorization": "Bearer example-token-123"
  }
}

• 이 문서의 example-token-123은 전달 형식을 확인하기 위한 가짜 token이다.
• 즉, 실제 인증 기능은 없다.

---

14.2 실제 token의 형태

Access token은 개발자가 임의로 작성하는 값이 아니라 인증 서버가 발급하는 문자열임.

Token의 형태는 인증 방식에 따라 달라진다.

임의 문자열 형태

a8f2c91d7e4b4c89b1c06d89184d52ef

사용 예는 다음과 같음:

curl "https://api.example.com/inference-results/101" \
  -H "Authorization: Bearer a8f2c91d7e4b4c89b1c06d89184d52ef"

 

JWT 형태

JWT는 마침표 .로 구분된 세 부분으로 구성됨:

HEADER.PAYLOAD.SIGNATURE

형태를 단순하게 나타내면 다음과 같음:

xxxxx.yyyyy.zzzzz

예를 들면 다음과 같은 긴 문자열임:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMDEiLCJyb2xlIjoidXNlciJ9.example_signature

• JWT 전체가 하나의 token 임.
• 따라서 중간에 공백이나 줄바꿈을 넣으면 안 됨.

curl "https://api.example.com/inference-results/101" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMDEiLCJyb2xlIjoidXNlciJ9.example_signature"

---

14.3 <ACCESS_TOKEN>의 의미

API 문서에서는 실제 token을 입력할 위치를 다음과 같이 표시하는 경우가 많음:

curl "https://api.example.com/inference-results/101" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

• 여기서 <ACCESS_TOKEN>은 실제로 발급받은 token으로 교체해야 함.

만약 발급받은 token이 다음과 같다고 가정한다면,

abc123xyz789

실제 명령은 다음과 같이 작성됨:

curl "https://api.example.com/inference-results/101" \
  -H "Authorization: Bearer abc123xyz789"

---

14.4 따옴표 사용

Header에는 공백이 포함되어 있으므로 header 전체를 따옴표로 감싸야 함

올바른 예는 다음과 같음:

-H "Authorization: Bearer example-token-123"

다음과 같이 따옴표를 사용하지 않으면 문자열이 여러 인자로 나뉘어 curl은 이를 여러 인자로 잘못 해석할 수 있음에 유의할 것.

따옴표를 감싸지 않으면 다음과 같은 오류가 발생할 수 있음:

curl: (6) Could not resolve host: Bearer

또한 문서에서 명령을 복사할 때 스마트 따옴표가 들어가지 않았는지 확인해야 한다.

정상: " " 또는 ' '
비정상: “ ” 또는 ‘ ’

• 겉으로는 비슷하지만 shell에서는 서로 다른 문자임.

---

14.5 환경 변수로 token 전달

실제 token은 명령어에 직접 작성하지 않고 환경 변수로 관리하는 편이 안전!

Linux, macOS, WSL

환경 변수에 token을 저장한다.

export ACCESS_TOKEN="example-token-123"

저장된 환경 변수를 사용한다.

curl \
  "https://httpbin.org/anything/inference-results/101" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

환경 변수를 사용할 때도 큰따옴표를 사용해야 함.

-H "Authorization: Bearer $ACCESS_TOKEN"

작은따옴표를 사용하면 $ACCESS_TOKEN이 실제 값으로 변환되지 않음에 유의.

-H 'Authorization: Bearer $ACCESS_TOKEN'

---

Windows PowerShell

다음과 같이 환경 변수에 token을 저장.

$env:ACCESS_TOKEN = "example-token-123"

다음과 같이 사용:

curl.exe "https://httpbin.org/anything/inference-results/101" `
  -H "Authorization: Bearer $env:ACCESS_TOKEN"

한 줄로 작성하면 다음과 같음:

curl.exe "https://httpbin.org/anything/inference-results/101" -H "Authorization: Bearer $env:ACCESS_TOKEN"

---

14.6 Token 사용 시 주의점

Access token은 비밀번호와 유사한 인증 정보임.

실제 token을 다음 위치에 직접 기록해선 안됨.

공개 GitHub 저장소
공개 게시판
화면 캡처
공유 문서
공유 shell script
프로그램 source code

예를 들어 다음처럼 source code 안에 직접 작성하는 방식은 피할 것:

ACCESS_TOKEN = "실제_token_문자열"

환경 변수나 별도의 secret 관리 기능을 사용하는 것이 적절함.

---

15. 이미지 파일 업로드

딥러닝 모델에 이미지 파일을 전달할 때는 multipart/form-data 형식을 사용하는 경우가 많음.

현재 폴더에 tongue.jpg 파일이 있다고 가정하면 다음의 명령어로 업로드 가능:

curl -X POST \
  "https://httpbin.org/anything/inference" \
  -F "file=@tongue.jpg" \
  -F "model=vit"

각 부분의 의미는 다음과 같음:

-F "file=@tongue.jpg" : tongue.jpg 파일을 file이라는 이름으로 전달
-F "model=vit"        : model이라는 일반 문자열 데이터를 함께 전달

파일 이름 앞의 @는 해당 파일의 내용을 읽어서 전송하라는 의미임:

@tongue.jpg

실제 딥러닝 추론 API에서는 다음과 같은 구조로 사용할 수 있음:

POST /api/inference
Content-Type: multipart/form-data

---

16. HTTP status code 확인

HTTP status code는 request가 성공했는지 또는 어떤 오류가 발생했는지를 나타냄.

16.1 200 확인

curl -i "https://httpbin.org/status/200"

HTTP/2 200

• 200 OK는 request가 정상적으로 처리되었다는 의미임.

---

16.2 404 확인

curl -i "https://httpbin.org/status/404"

HTTP/2 404

• 404 Not Found는 요청한 리소스를 찾을 수 없다는 의미임.

---

16.3 500 확인

curl -i "https://httpbin.org/status/500"

HTTP/2 500

• 500 Internal Server Error는 서버 내부에서 오류가 발생했다는 의미임.

---

16.4 Status code만 출력

Linux, macOS, WSL에서는 다음과 같이 status code만 출력할 수 있음:

curl -s -o /dev/null -w "%{http_code}\n" \
  "https://httpbin.org/status/404"

 

출력은 다음과 같음:

404

 

각 option의 의미는 다음과 같음:

Option	의미
-s	진행 상태를 출력하지 않음
-o /dev/null	response body를 출력하지 않음
-w	요청이 끝난 뒤 지정한 정보를 출력
%{http_code}	HTTP status code

 

참고로 Windows에서는 /dev/null 대신 NUL을 사용함:

curl.exe -s -o NUL -w "%{http_code}`n" "https://httpbin.org/status/404"

---

17. 종합 실습

다음 명령을 순서대로 실행하고 응답의 method, json, headers, url을 비교한다.

17.1 GET

curl -i \
  "https://httpbin.org/anything/inference-results/101"

확인할 내용:

method가 GET인지 확인한다.

---

17.2 POST

curl -i -X POST \
  "https://httpbin.org/anything/inference-results" \
  -H "Content-Type: application/json" \
  -d '{"image":"tongue_001.jpg","model":"vit"}'

 

확인할 내용:

method가 POST인지 확인한다.
json에 image와 model이 포함되었는지 확인한다.

---

17.3 PUT

curl -i -X PUT \
  "https://httpbin.org/anything/inference-results/101" \
  -H "Content-Type: application/json" \
  -d '{"id":101,"image":"tongue_001.jpg","label":"cancer","reviewed":false}'

 

확인할 내용:

리소스의 전체 내용을 request body로 전달했는지 확인한다.

---

17.4 PATCH

curl -i -X PATCH \
  "https://httpbin.org/anything/inference-results/101" \
  -H "Content-Type: application/json" \
  -d '{"reviewed":true}'

확인할 내용:

수정할 reviewed 필드만 전달했는지 확인한다.

---

17.5 DELETE

curl -i -X DELETE \
  "https://httpbin.org/anything/inference-results/101"

확인할 내용:

method가 DELETE인지 확인한다.

---

17.6 HEAD

curl -I \
  "https://httpbin.org/anything/inference-results/101"

 

확인할 내용:

response body 없이 header만 출력되는지 확인한다.

---

17.7 OPTIONS

curl -i -X OPTIONS \
  "https://httpbin.org/anything/inference-results/101"

 

확인할 내용:

method가 OPTIONS인지 확인한다.

---

17.8 Authorization header

curl -i \
  "https://httpbin.org/anything/inference-results/101" \
  -H "Authorization: Bearer example-token-123"

 

확인할 내용:

응답의 headers에 Authorization 값이 포함되는지 확인한다.

---

18. 정리

HTTP method의 의미는 다음과 같다.

• GET : 리소스를 조회.
• POST : 새로운 리소스를 생성하거나 처리를 요청.
• PUT : 기존 리소스의 전체 내용을 교체.
• PATCH : 기존 리소스의 일부 내용만 수정.
• DELETE : 기존 리소스를 삭제.
• HEAD : response body 없이 header만 확인.
• OPTIONS : 서버가 지원하는 method나 기능을 확인.

자주 사용하는 curl option은 다음과 같음:

Option	의미
-X METHOD	사용할 HTTP method 지정
-H HEADER	request header 추가
-d DATA	request body 전달
-F DATA	파일 또는 form data 전달
-i	response header와 body를 함께 출력
-I	HEAD request 수행
-v	통신 과정을 자세히 출력
-s	진행 상태를 출력하지 않음
-o FILE	response body를 파일로 저장
-w FORMAT	status code 등의 결과를 별도로 출력

---

같이 보면 좋은 자료들

2025.08.29 - [Python] - [requests] Python의 requests 라이브러리 사용법.

[requests] Python의 requests 라이브러리 사용법.

2025.08.28 - [Python] - [urllib] request 모듈

[urllib] request 모듈

2025.08.07 - [Python] - webbrowser 모듈 사용법

webbrowser 모듈 사용법

2025.08.06 - [Python] - urllib.parse.quote, urllib.parse.urlencode

urllib.parse.quote, urllib.parse.urlencode

---