API 테스트 시 HTTP 요청으로 데이터를 보내거나 파일을 다운로드해야 하는데, 복잡한 curl 옵션 때문에 매번 검색하고 있나요?
이런 번거로움은 `curl` 명령어의 방대한 기능과 옵션이 체계적으로 정리되지 않아 발생합니다.
이 글에서는 데이터 전송부터 파일 다운로드까지, 현장에서 가장 자주 사용되는 `curl` 명령어 실전 예제를 통해 반복적인 검색 없이 즉시 활용할 수 있는 방법을 제시합니다.
– `curl`의 기본 GET/POST 요청부터 고급 옵션까지 실전 예제로 정리합니다.
– JSON, 폼 데이터 등 다양한 형식의 데이터 전송 방법을 명확히 설명합니다.
– 파일 업로드 및 다운로드, 헤더 설정, 인증 등 복잡한 시나리오에 즉시 적용 가능합니다.
curl 명령어를 활용하여 HTTP 요청 전송 및 파일 업로드/다운로드 실전 방법을 예제와 함께 자세히 알아봅니다.
curl 명령어 기초 다지기: GET/POST 요청
`curl`은 Command Line URL의 약자로, 터미널에서 다양한 프로토콜을 이용해 데이터를 전송하거나 다운로드할 수 있는 강력한 도구입니다. 웹 개발에서 API 테스트, 서버 상태 확인, 데이터 스크래핑 등 수많은 상황에서 핵심적인 역할을 합니다. 복잡해 보이지만, 자주 사용하는 몇 가지 옵션만 익히면 약 80% 이상의 실전 상황에 대응할 수 있습니다.
가장 기본이 되는 요청 방식은 GET과 POST입니다. GET은 주로 데이터를 조회할 때 사용하며, POST는 서버로 새로운 데이터를 생성하거나 전송할 때 사용합니다. 이 두 가지 요청을 마스터하는 것이 `curl` 활용의 첫걸음입니다.
`curl` 명령어는 기본적으로 GET 요청을 수행합니다. 특정 URL을 `curl` 뒤에 붙여주기만 하면 해당 URL의 내용을 가져옵니다. POST 요청은 `-X POST` 옵션을 명시하고, 전송할 데이터를 `-d` 옵션으로 추가합니다.
- GET 요청 기본 — 특정 URL의 리소스를 조회합니다. 가장 단순한 `curl` 사용법입니다.
curl https://api.example.com/users - POST 요청 기본 — 서버로 데이터를 전송하여 새로운 리소스를 생성하거나 업데이트합니다. `-X POST` 옵션과 함께 `-d`로 데이터를 지정합니다.
curl -X POST -d "name=John Doe&email=john@example.com" https://api.example.com/users
Photo by Hairlust Official on Pexels
데이터 전송의 정석: JSON과 폼 데이터 다루기
현대 웹 API 통신에서는 JSON(JavaScript Object Notation)과 폼(Form) 데이터가 거의 100%에 가깝게 사용됩니다. 특히 RESTful API에서는 JSON 형식이 표준처럼 자리 잡았습니다. `curl`로 이러한 데이터 형식을 정확히 전송하는 방법을 아는 것은 API 개발 및 테스트에서 매우 중요합니다.
JSON 데이터를 보낼 때는 HTTP 헤더에 `Content-Type: application/json`을 명시해야 서버가 데이터를 올바르게 해석할 수 있습니다. `-H` 옵션으로 헤더를 추가하고, `-d` 옵션으로 JSON 문자열을 직접 전달합니다. 복잡한 JSON 데이터는 파일로 저장한 후 `@` 접두사를 사용해 전송할 수도 있습니다.
폼 데이터는 HTML 폼을 통해 전송되는 전통적인 방식으로, `application/x-www-form-urlencoded` 또는 파일 업로드를 포함하는 `multipart/form-data` 두 가지 형태가 있습니다. URL 인코딩된 폼 데이터는 `-d` 옵션으로 바로 전달할 수 있으며, `Content-Type`은 `curl`이 자동으로 설정해줍니다.
| 구분 | JSON 데이터 전송 | 폼 데이터 전송 |
|---|---|---|
| 사용 목적 | RESTful API에 구조화된 데이터 전달 | HTML 폼 제출, 간단한 키-값 데이터 전달 |
| curl 명령어 예시 | curl -X POST -H "Content-Type: application/json" -d '{"title":"새 글", "content":"내용입니다"}' https://api.example.com/posts |
curl -X POST -d "username=user123&password=pass" https://api.example.com/login |
| 주요 옵션 | -H "Content-Type: application/json", -d '{...}' |
-d "key=value&..." |
Photo by Engin Akyurt on Pexels
파일 처리 마스터: 업로드 및 다운로드
개발 환경에서 서버에 파일을 업로드하거나 원격 서버에서 파일을 다운로드해야 하는 상황은 빈번하게 발생합니다. 이미지, 문서, 설정 파일 등 다양한 종류의 파일을 `curl`로 효율적으로 처리할 수 있습니다. 특히 스크립트 내에서 자동화된 파일 전송이 필요할 때 `curl`은 매우 유용합니다.
파일 업로드 시에는 `-F` (form) 옵션을 사용하여 `multipart/form-data` 형식으로 파일을 첨부합니다. 파일 경로 앞에 `@`를 붙여야 `curl`이 이를 파일로 인식합니다. 파일 외에 다른 폼 필드도 함께 전송할 수 있으며, 이는 웹 서비스의 파일 업로드 API 테스트에 특히 유용합니다.
파일 다운로드는 `-O` 또는 `-o` 옵션을 사용합니다. `-O`는 원격 파일 이름을 그대로 사용하여 현재 디렉토리에 저장하며, `-o`는 저장할 파일 이름을 직접 지정할 수 있습니다. 예를 들어, 웹에서 제공하는 특정 설치 스크립트나 대용량 데이터 파일을 다운로드할 때 매우 효과적입니다. 수백 MB 크기의 파일도 문제없이 처리 가능합니다.
파일 업로드 시 `-F` 옵션은 `multipart/form-data` 헤더를 자동으로 설정합니다. 만약 파일이 아닌 일반 텍스트 필드를 함께 보내고 싶다면, `-F “username=testuser”`와 같이 사용하고 파일은 `-F “file=@/path/to/your/file.txt”` 형태로 구분하여 지정합니다.
다음은 파일 업로드 및 다운로드의 실전 예시입니다.
- 파일 업로드 — 로컬 파일을 지정된 URL로 전송합니다.
curl -X POST -F "document=@/home/user/report.pdf" -F "description=2023년 보고서" https://api.example.com/upload - 파일 다운로드 — 원격 URL의 파일을 로컬에 저장합니다.
curl -O https://example.com/archive.zip(archive.zip으로 저장)
curl -o local_archive.zip https://example.com/archive.zip(local_archive.zip으로 저장)
Photo by Engin Akyurt on Pexels
고급 활용: 헤더, 인증, 리다이렉션 제어
`curl`은 단순히 데이터 전송을 넘어, HTTP 요청의 세부적인 부분을 제어할 수 있는 강력한 고급 옵션들을 제공합니다. 커스텀 헤더 추가, 사용자 인증, 리다이렉션 자동 처리, 타임아웃 설정 등은 특정 API의 복잡한 요구사항을 만족시키거나 네트워크 환경에 유연하게 대응할 때 필수적입니다.
HTTP 헤더는 요청이나 응답에 대한 추가 정보를 담고 있습니다. 인증 토큰, 사용자 에이전트, 캐시 제어 등 다양한 용도로 사용되며, `-H` 옵션으로 직접 지정할 수 있습니다. 예를 들어, JWT(JSON Web Token) 기반 인증을 사용하는 API에 요청을 보낼 때 `Authorization` 헤더를 추가해야 합니다.
API에 접근하기 위한 사용자 인증은 `-u` 옵션을 통해 처리할 수 있습니다. 기본적으로 `Basic` 인증을 사용하며, `–anyauth` 옵션을 추가하면 서버가 지원하는 다른 인증 방식(Digest, NTLM 등)을 `curl`이 자동으로 선택하도록 할 수 있습니다. 또한, 웹 페이지가 다른 URL로 리다이렉션될 때 이를 자동으로 따라가려면 `-L` (Location) 옵션을 사용해야 합니다. 네트워크 지연이나 응답 없음 상황을 방지하기 위해 `–max-time` 옵션으로 최대 응답 대기 시간을 3초 또는 5초 등으로 설정하는 것도 좋은 습관입니다.
인증 정보를 `curl` 명령에 직접 명시할 경우, 터미널 히스토리나 로그에 노출될 위험이 있습니다. 보안에 민감한 정보는 환경 변수나 설정 파일을 통해 관리하는 것이 안전합니다. 테스트 목적으로만 짧게 사용하는 것이 좋습니다.
다음은 고급 활용 예시입니다.
- 커스텀 헤더 및 인증 — API 키나 토큰을 헤더에 추가하거나 사용자 이름과 비밀번호로 인증합니다.
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://api.example.com/data
curl -u "username:password" https://api.example.com/secure_data - 리다이렉션 및 타임아웃 — HTTP 리다이렉션을 자동으로 따르고, 요청에 최대 대기 시간을 설정합니다.
curl -L https://shorturl.at/abcde
curl --max-time 5 https://slowapi.example.com/data
이 글에서는 `curl` 명령어의 기본적인 GET/POST 요청부터 JSON 및 폼 데이터 전송, 파일 업로드/다운로드, 그리고 헤더와 인증, 리다이렉션 제어 같은 고급 활용법까지 실전 예제를 통해 자세히 살펴보았습니다. 이제 `curl`의 다양한 옵션들을 더 이상 헤매지 않고 능숙하게 사용할 수 있을 것입니다.
지금 바로 적용해 보세요.
- curl 공식 매뉴얼 — `curl` 명령어의 모든 옵션과 상세한 사용법이 정리되어 있습니다.
- MDN Web Docs: HTTP 개요 — HTTP 프로토콜의 기본 개념과 동작 원리를 이해하는 데 도움이 됩니다.
동영상으로 보는 curl 명령어 실전 예제
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
자주 묻는 질문
Q. 가장 기본적인 HTTP GET 요청은 어떻게 하나요?
A. 기본적으로 `curl [URL]` 형식으로 사용하며, 웹 페이지 콘텐츠를 가져오거나 API 데이터를 조회할 때 유용합니다. 추가 옵션 없이도 서버 응답을 표준 출력으로 바로 확인할 수 있습니다.
Q. 데이터를 포함하여 POST 요청을 보내려면 어떻게 해야 하나요?
A. `-X POST` 옵션과 함께 `-d` 옵션을 사용하여 데이터를 전송할 수 있습니다. JSON 형식의 데이터를 보낼 경우 `–header “Content-Type: application/json”` 옵션을 함께 사용하는 것이 일반적입니다.
Q. 웹 서버에서 파일을 다운로드하는 방법은 무엇인가요?
A. `-O` (대문자 O) 옵션을 사용하면 원본 파일 이름 그대로 현재 디렉터리에 저장됩니다. 만약 다른 이름으로 저장하고 싶다면 `-o [새_파일_이름]` (소문자 o) 옵션을 활용할 수 있습니다.
Q. 로컬 파일을 HTTP를 통해 서버로 업로드하려면 어떤 명령어를 사용해야 하나요?
A. 파일 업로드 시에는 `-F` 또는 `–form` 옵션을 사용하여 파일을 첨부할 수 있습니다. `curl -X POST -F “file=@/path/to/local/file” [업로드_URL]`과 같은 형식으로 주로 사용됩니다.
📚 함께 읽으면 좋은 글