개발 중 API 연동 테스트를 위해 복잡한 JSON 데이터를 curl로 보내거나, 파일 내용을 통째로 POST 요청해야 할 때마다 검색하고 있나요? 매번 Stack Overflow나 블로그를 뒤적이며 옵션 하나하나를 맞춰보느라 귀중한 개발 시간을 낭비하고 있다면, 이 글이 바로 당신을 위한 것입니다.
이러한 반복적인 검색은 curl 명령어의 핵심 옵션과 활용법에 대한 명확한 이해가 부족하기 때문에 발생합니다. 기본적인 GET 요청부터 복잡한 데이터 전송, 그리고 인증 처리까지, 실제 개발 환경에서는 다양한 시나리오에 맞는 정확한 curl 사용법이 필요합니다.
이 글에서는 자주 사용하는 데이터 타입별 curl 요청 방법과 파일 전송, 그리고 API 인증 처리까지, 실제 개발 환경에서 바로 적용할 수 있는 5가지 핵심 시나리오를 단계별로 안내합니다. 이제 더 이상 검색에 시간을 낭비하지 마세요.
– JSON 및 폼 데이터 전송 시 `Content-Type` 헤더와 `-d` 또는 `-F` 옵션의 정확한 활용법.
– 파일 내용을 통째로 API 요청 본문에 포함하거나, `multipart/form-data`로 파일을 업로드하는 실전 노하우.
– HTTP 기본 인증부터 Bearer 토큰 방식까지, 다양한 API 인증 메커니즘을 curl로 처리하는 방법.
curl 기본: 가장 간단한 GET 요청
curl은 명령줄 인터페이스(CLI)에서 HTTP, FTP, SMTP 등 다양한 네트워크 프로토콜을 통해 데이터를 전송하는 데 사용되는 강력한 도구입니다. 개발 환경에서 API 테스트를 할 때, 특정 URL로 GET 요청을 보내 응답을 확인하는 것은 가장 기본적인 사용법이자 하루에도 수십 번씩 사용하게 되는 동작입니다.
웹 브라우저가 사용자 대신 하는 일을 터미널에서 직접 수행한다고 생각하면 이해하기 쉽습니다. 특별한 데이터 전송 없이 특정 리소스의 내용을 가져오는 경우에는 추가 옵션 없이 URL만 지정해도 충분합니다. 기본적으로 curl은 GET 요청을 보냅니다.
아래 예제는 `https://api.example.com/data`라는 가상의 엔드포인트에 GET 요청을 보내는 방법을 보여줍니다. 이 명령어를 실행하면 해당 URL의 응답 본문이 터미널에 출력됩니다.
curl https://api.example.com/dataAPI 응답 본문뿐만 아니라, HTTP 응답 헤더까지 함께 보고 싶다면 `-i` (또는 `–include`) 옵션을 사용하거나, 더욱 상세한 통신 과정을 보려면 `-v` (또는 `–verbose`) 옵션을 추가하면 됩니다. 예를 들어 `curl -i https://api.example.com/data`와 같이 사용할 수 있습니다.
Photo by Marc Mueller on Pexels
JSON 데이터 전송: POST 및 PUT 요청
대부분의 RESTful API는 JSON(JavaScript Object Notation) 형식으로 데이터를 주고받습니다. 특히 새로운 리소스를 생성하는 `POST` 요청이나 기존 리소스를 업데이트하는 `PUT` 요청에서는 JSON 데이터를 본문에 담아 보내는 것이 일반적입니다. curl로 JSON 데이터를 보내려면 세 가지 핵심 요소를 정확하게 지정해야 합니다.
첫째, 요청 방식(`-X POST` 또는 `-X PUT`)을 명시해야 합니다. 둘째, `Content-Type` 헤더를 `application/json`으로 설정해야 합니다. 이는 서버에게 “내가 보내는 데이터는 JSON 형식이야”라고 알려주는 역할을 합니다. 셋째, `-d` (또는 `–data`) 옵션을 사용하여 전송할 JSON 데이터를 지정합니다. JSON 데이터는 일반적으로 작은따옴표로 감싸며, 내부의 큰따옴표는 별도로 이스케이프할 필요가 없습니다. 다만, 윈도우 환경에서는 이스케이프 처리가 필요할 수 있습니다.
다음은 사용자 정보를 JSON 형식으로 POST 요청을 보내는 예시입니다. API 서버는 이 정보를 받아 새로운 사용자 리소스를 생성할 것입니다.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name": "김철수", "age": 30, "city": "서울"}' \
https://api.example.com/users윈도우 명령 프롬프트(CMD) 환경에서는 `-d` 옵션의 JSON 문자열을 이중 큰따옴표로 감싸고, 내부의 큰따옴표는 백슬래시(`\`)로 이스케이프해야 합니다. 예를 들어, `-d “{\”name\”: \”김철수\”, \”age\”: 30}”`와 같이 작성해야 합니다. PowerShell에서는 Linux/macOS와 유사하게 작은따옴표를 사용할 수 있습니다.
Photo by Markus Spiske on Pexels
폼(Form) 데이터 전송: x-www-form-urlencoded와 multipart/form-data
웹 개발에서 자주 접하는 데이터 전송 형식으로는 `application/x-www-form-urlencoded`와 `multipart/form-data`가 있습니다. 전자는 HTML 폼의 기본 전송 방식이며, 후자는 주로 파일 업로드에 사용됩니다. 각 방식은 curl에서 다른 옵션을 사용합니다.
`application/x-www-form-urlencoded` 방식은 키-값 쌍을 `&`로 연결하고 값을 URL 인코딩하는 방식입니다. curl의 `-d` 옵션을 사용하여 데이터를 지정하면, curl이 자동으로 `Content-Type: application/x-www-form-urlencoded` 헤더를 추가합니다. 반면 `multipart/form-data`는 파일과 다른 텍스트 데이터를 함께 전송할 수 있는 복잡한 형식으로, `-F` (또는 `–form`) 옵션을 사용해야 합니다. 이 옵션을 사용하면 curl이 `Content-Type: multipart/form-data` 헤더를 자동으로 설정하고, 각 필드를 적절한 형식으로 인코딩하여 전송합니다.
파일을 업로드하는 상황에서는 반드시 `-F` 옵션을 사용해야 합니다. 파일 경로 앞에 `@` 기호를 붙여 curl에게 로컬 파일을 참조하도록 지시합니다. 예를 들어, `profile.jpg` 파일을 업로드하면서 사용자 이름(`username`)도 함께 보내는 경우를 살펴보겠습니다. 이 방식을 통해 여러 개의 파일과 필드를 한 번에 전송할 수 있습니다.
# x-www-form-urlencoded 데이터 전송 (로그인 예시)
curl -X POST \
-d "username=user123&password=pass456" \
https://api.example.com/login
# multipart/form-data를 이용한 파일 업로드 (가상의 profile.jpg 파일 업로드)
curl -X POST \
-F "username=devuser" \
-F "profile=@./profile.jpg" \
https://api.example.com/upload| 구분 | `-d` (데이터 옵션) | `-F` (폼 옵션) |
|---|---|---|
| 주요 용도 | JSON, `x-www-form-urlencoded` 문자열 전송 | 파일 업로드, `multipart/form-data` 전송 |
| `Content-Type` | 자동 또는 수동으로 `application/json`, `application/x-www-form-urlencoded` 설정 | 자동으로 `multipart/form-data` 설정 |
| 데이터 형식 | 단일 문자열 본문 (JSON) 또는 `key1=value1&key2=value2` 형식 | 개별 필드 또는 파일(경로 앞에 `@` 붙임) 전송 |
| 예시 | `curl -d ‘{“name”:”Alice”}’` 또는 `curl -d “user=test”` | `curl -F “file=@/path/to/img.png”` 또는 `curl -F “text_field=value”` |
파일 내용 통째로 전송하기
때로는 파일의 내용을 JSON이나 폼 데이터가 아닌, 그 자체로 API 요청의 본문으로 보내야 할 때가 있습니다. 예를 들어, 텍스트 파일, XML 파일, CSV 파일 등을 특정 엔드포인트에 직접 업로드하거나, 특정 API에서 바이너리 데이터를 직접 요구하는 경우가 여기에 해당합니다. 이럴 때는 `–data-binary` (또는 `-T`) 옵션을 사용합니다.
`–data-binary`는 파일의 내용을 있는 그대로(raw) 전송합니다. 즉, 줄 바꿈이나 특수 문자 인코딩에 신경 쓸 필요 없이 파일 경로만 지정하면 됩니다. 이는 특히 대용량 로그 파일이나 이미지 파일 등을 직접 API로 전송할 때 매우 유용합니다. 파일 경로 앞에 `@` 기호를 붙여 로컬 파일을 참조하도록 지시하며, 적절한 `Content-Type` 헤더를 수동으로 지정해주는 것이 좋습니다.
다음은 `document.txt`라는 텍스트 파일의 내용을 API 서버로 POST 요청의 본문으로 전송하는 예시입니다. `Content-Type`은 `text/plain`으로 지정했습니다.
curl -X POST \
--data-binary "@./document.txt" \
-H "Content-Type: text/plain" \
https://api.example.com/documents/upload- 전송할 파일 준비 — `./document.txt`와 같이 전송하려는 파일이 로컬에 존재하며 접근 가능한지 확인합니다. 파일 내용은 API의 요구사항에 맞춰야 합니다.
- 요청 방식 및 URL 지정 — `curl -X POST https://api.example.com/documents/upload`와 같이 적절한 HTTP 요청 방식(POST, PUT 등)과 데이터를 보낼 목적지 URL을 설정합니다.
- `–data-binary` 옵션으로 파일 경로 지정 — `–data-binary “@./document.txt”`를 추가하여 파일 내용을 요청 본문으로 보냅니다. 필요에 따라 `-H “Content-Type: text/plain”` 등 올바른 `Content-Type` 헤더를 설정합니다.
API 인증 처리: Basic Auth와 Bearer 토큰
실제 운영되는 대부분의 API는 보안을 위해 인증을 요구합니다. 인증 정보가 없거나 잘못되면 401 Unauthorized 오류를 받게 됩니다. curl은 HTTP 기본 인증(Basic Auth)과 Bearer 토큰 방식 등 다양한 인증 메커니즘을 지원하며, 이를 통해 보호된 리소스에 접근할 수 있습니다.
HTTP 기본 인증은 사용자 이름과 비밀번호를 `-u` (또는 `–user`) 옵션으로 전달하여 처리합니다. `username:password` 형식으로 입력하면 curl이 자동으로 이 정보를 Base64로 인코딩하여 `Authorization: Basic [encoded_string]` 형태의 헤더를 생성하여 요청에 포함시킵니다. Bearer 토큰 방식은 `Authorization` 헤더에 직접 토큰을 넣어 전달하는 방식입니다. `Authorization: Bearer YOUR_ACCESS_TOKEN` 형태로 `-H` 옵션을 사용하여 헤더를 추가합니다.
아래 예시를 통해 두 가지 인증 방식의 사용법을 확인할 수 있습니다. API마다 요구하는 인증 방식이 다르므로, 해당 API 문서를 참고하여 올바른 방식을 사용해야 합니다. 보통 Bearer 토큰 방식은 OAuth 2.0과 같은 최신 인증 프로토콜에서 많이 사용됩니다.
# HTTP 기본 인증 (Basic Auth) 예시
curl -u "myuser:mypassword123" https://api.example.com/protected
# Bearer 토큰 인증 예시 (YOUR_ACCESS_TOKEN 대신 실제 토큰 사용)
curl -H "Authorization: Bearer a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" https://api.example.com/protected보안을 위해 실제 비밀번호나 API 토큰은 터미널 기록에 직접 노출되지 않도록 환경 변수로 관리하거나, 안전한 방법으로 전달하는 것을 권장합니다. 특히 Bearer 토큰은 60분에서 24시간 정도의 유효 기간을 가지는 경우가 많으니 만료 시간을 확인해야 합니다. 개발 환경에서는 편의상 직접 입력하지만, 프로덕션 환경에서는 더욱 신중한 접근이 필요합니다.
curl 명령어는 복잡한 API 연동 테스트와 다양한 데이터 전송에서 개발자의 생산성을 획기적으로 높여주는 강력한 도구입니다. 이 가이드에서 다룬 5가지 핵심 시나리오만 숙지해도 80% 이상의 실전 문제를 해결할 수 있습니다. 이제 더 이상 API 테스트마다 검색에 시간을 낭비하지 않고, 다양한 데이터를 효율적으로 전송하고 인증을 처리하는 자신감을 얻으셨기를 바랍니다.
지금 바로 적용해 보세요.
- curl 공식 매뉴얼 — curl 명령어의 모든 옵션과 자세한 사용법을 확인할 수 있는 공식 문서입니다.
- MDN Web Docs: Content-Type — HTTP Content-Type 헤더에 대한 심층적인 설명과 사용 예시를 제공합니다.
동영상으로 보는 curl 명령어 API 요청 실전
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
자주 묻는 질문
Q. curl로 API 요청 시 인증은 어떻게 처리하나요?
A. curl은 다양한 인증 방식을 지원합니다. 베이직 인증은 `-u username:password` 옵션을, API 키나 Bearer 토큰은 `-H “Authorization: Bearer YOUR_TOKEN”`과 같이 헤더를 통해 전달할 수 있습니다. 각 API의 요구 사항에 맞춰 적절한 인증 방식을 선택하여 사용해야 합니다.
Q. 복잡한 JSON 데이터를 curl로 전송하려면 어떻게 해야 하나요?
A. 복잡한 JSON 데이터를 전송할 때는 `-H “Content-Type: application/json”` 헤더를 반드시 포함해야 합니다. JSON 문자열이 길거나 복잡하다면, `-d @filename.json` 옵션을 사용하여 JSON 데이터가 담긴 파일을 본문으로 전송하는 것이 가독성과 유지보수 측면에서 더 좋습니다.
Q. curl로 파일을 전송할 때 `-F`와 `-d` 옵션의 차이점은 무엇인가요?
A. `-F` (form-data) 옵션은 `multipart/form-data` 형식으로 파일을 업로드할 때 사용되며, 파일 자체와 추가 필드를 함께 보낼 수 있습니다. 반면 `-d` (data) 옵션은 일반적인 POST 요청 본문에 데이터를 포함할 때 사용하며, 파일 첨부 시에는 `@filename` 형태로 파일의 내용을 본문에 직접 포함하는 방식으로 동작합니다.
Q. curl 요청이 제대로 작동하는지 확인하거나 문제 발생 시 디버깅하려면 어떻게 해야 하나요?
A. curl 요청의 상세 정보를 확인하거나 디버깅하려면 `-v` (verbose) 옵션을 사용하면 좋습니다. 이 옵션은 요청 및 응답 헤더, SSL/TLS 협상 과정 등 통신 전반에 대한 자세한 정보를 출력해주어 문제의 원인을 파악하는 데 큰 도움이 됩니다.
함께 읽으면 좋은 글