API 응답을 확인하거나 파일을 서버에 전송해야 할 때, curl 명령어로 빠르고 효율적으로 작업하고 싶으신가요? 터미널에서 간단한 명령어로 복잡한 작업을 처리할 수 있다면 개발 생산성이 비약적으로 향상될 것입니다.
함께 보면 좋은 글: 노션 API 자동화, 반복 업무 싹 없애는 예제 모음
하지만 curl 명령어의 방대한 옵션과 복잡한 문법 때문에 처음에는 막막하게 느껴질 수 있습니다. 어떤 옵션을 써야 할지, 어떻게 조합해야 원하는 결과를 얻을 수 있을지 혼란스러울 수 있습니다.
이 글에서는 curl 명령어의 기본 원리부터 시작하여 API 테스트, 파일 전송, 그리고 실제 개발 환경에서 마주칠 수 있는 다양한 문제 해결까지, 실전에서 바로 활용할 수 있는 구체적인 사용법을 단계별로 자세히 안내합니다. 복잡한 GUI 도구 없이 터미널만으로도 능숙하게 API와 상호작용하는 방법을 익힐 수 있습니다.
- curl 명령어의 기본 구조와 주요 옵션을 이해하고 API 요청 및 응답 확인에 활용하는 방법을 배웁니다.
- HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 다양한 API 엔드포인트와 상호작용하는 실전 예제를 익힙니다.
- 파일 업로드 및 다운로드, 인증 처리, 헤더 조작 등 고급 기능을 마스터하여 복잡한 서버 작업을 효율적으로 수행합니다.
curl 명령어는 API 테스트, 데이터 조회, 파일 전송 등 다양한 실전 활용법을 통해 개발 생산성을 80% 이상 향상시키고, 복잡한 작업을 단 5단계 만에 완료하도록 돕는 강력한 도구입니다.
curl 명령어, 무엇이며 왜 사용해야 할까요?
curl은 'Client URL'의 약자로, 다양한 프로토콜을 사용하여 데이터를 전송하고 수신할 수 있는 강력한 커맨드라인 도구입니다. URL 구문을 사용하여 서버와 통신하며, HTTP, HTTPS, FTP, SCP 등 수많은 프로토콜을 지원합니다. 대부분의 운영체제에 기본적으로 설치되어 있거나 쉽게 설치할 수 있어 접근성이 매우 뛰어납니다.
API 개발자, 시스템 관리자, 웹 개발자 등에게 curl은 필수적인 도구로 자리 잡았습니다. GUI 기반의 API 테스트 도구들이 많이 있지만, curl은 스크립트 자동화, 서버 환경에서의 즉각적인 테스트, 그리고 미묘한 네트워크 문제 진단에 있어 비교할 수 없는 유연성과 효율성을 제공합니다. 예를 들어, 복잡한 설정 없이 바로 서버의 특정 API 엔드포인트에 요청을 보내고 응답을 확인하는 작업은 curl로 몇 초 안에 가능합니다.
"개발서버의 터미널 root 권한을 줬더니, 도커이미지 작업부터 컨테이너 작업, 서버작업, 클라이언트를 위한 ui 작업까지 하네요. 심지어 파이썬으로 스크립트 만들어 curl 때려가며 그걸 테스트까지 합니다." (출처: clien.net) 이처럼 실제 개발 현장에서는 curl이 자동화된 워크플로우의 핵심적인 역할을 수행하는 것을 볼 수 있습니다. 이러한 자동화와 효율성은 curl이 제공하는 강력한 기능과 다양한 옵션 덕분입니다.
기본부터 탄탄하게: API 요청 및 응답 확인
curl 명령어의 가장 기본적인 형태는 특정 URL로 GET 요청을 보내고 그 결과를 표준 출력으로 보여주는 것입니다. 예를 들어, 공개된 API의 데이터를 가져올 때 다음과 같이 사용합니다.
curl https://jsonplaceholder.typicode.com/posts/1이 명령어는 `jsonplaceholder.typicode.com`의 `/posts/1` 경로로 GET 요청을 보내고, 서버로부터 받은 JSON 형식의 응답 데이터를 터미널에 출력합니다. 응답 데이터의 내용뿐만 아니라 HTTP 헤더 정보까지 확인하고 싶다면 `-i` 옵션을 사용합니다.
curl -i https://jsonplaceholder.typicode.com/posts/1`-i` 옵션을 사용하면 HTTP 상태 코드(예: 200 OK, 404 Not Found), Content-Type, Date 등 응답 헤더 정보와 함께 본문 데이터가 표시됩니다. 응답 헤더만 보고 싶다면 `-I` (대문자 아이) 옵션을 사용하면 됩니다. 이는 주로 서버 응답 속도나 캐시 정책 등을 빠르게 파악할 때 유용합니다. 또한, curl은 기본적으로 연결이 성공하면 100초 동안 응답을 기다리는데, 이 타임아웃 시간을 조절하고 싶다면 `-m` 옵션을 사용할 수 있습니다. 예를 들어, 30초로 제한하려면 다음과 같이 입력합니다.
curl -m 30 https://example.com성능 테스트나 불안정한 네트워크 환경에서의 요청 시, 이러한 타임아웃 설정은 필수적입니다. Google 개발자 문서에서 명시한 바로는, API 응답 시간을 2.5초 이하로 유지하는 것이 사용자 경험에 매우 긍정적인 영향을 미치므로, curl로 응답 시간을 측정하고 최적화하는 작업은 중요합니다.
실전 API 테스트: 다양한 HTTP 메서드 활용
동영상으로 보는 curl 명령어 실전 사용법
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
RESTful API는 GET, POST, PUT, DELETE 등 다양한 HTTP 메서드를 사용하여 리소스에 대한 작업을 수행합니다. curl은 이러한 모든 메서드를 지원하며, `-X` 옵션을 사용하여 원하는 메서드를 명시할 수 있습니다. 예를 들어, 새로운 게시물을 생성하기 위해 POST 요청을 보내는 경우는 다음과 같습니다.
curl -X POST -d '{"title": "foo", "body": "bar", "userId": 1}' https://jsonplaceholder.typicode.com/posts여기서 `-d` 옵션은 POST 요청의 본문(body) 데이터를 지정합니다. JSON 데이터를 보낼 때는 Content-Type 헤더를 `application/json`으로 설정하는 것이 일반적이며, curl은 `-H` 옵션을 통해 헤더를 추가할 수 있습니다. 위의 예제는 `-d` 옵션만 사용해도 서버가 이를 JSON으로 인식하는 경우이지만, 명시적으로 헤더를 설정하는 것이 더 정확하고 안전합니다.
curl -X POST -H "Content-Type: application/json" -d '{"title": "foo", "body": "bar", "userId": 1}' https://jsonplaceholder.typicode.com/posts데이터를 수정할 때는 PUT 메서드를, 리소스를 삭제할 때는 DELETE 메서드를 사용합니다. 예를 들어, 특정 게시물을 삭제하는 요청은 다음과 같습니다.
curl -X DELETE https://jsonplaceholder.typicode.com/posts/1이처럼 curl은 다양한 HTTP 메서드를 지원하여 복잡한 API 엔드포인트와 효과적으로 상호작용할 수 있게 해줍니다. 이러한 메서드들을 조합하여 실제 서비스에서 발생하는 다양한 API 호출 시나리오를 테스트하고 디버깅할 수 있습니다. 실제 사용자는 종종 이러한 API 호출 결과를 스크립트로 만들어 반복적인 작업을 자동화하는데, curl은 이 과정에서 핵심적인 역할을 합니다. 예를 들어, 100개의 데이터를 생성하고 검증하는 과정을 스크립트 하나로 처리할 수 있습니다.
API 요청 시 발생할 수 있는 오류를 디버깅할 때, `-v` (verbose) 옵션은 매우 유용합니다. 이 옵션을 사용하면 요청 헤더, 응답 헤더, 그리고 SSL/TLS 핸드셰이크 정보 등 상세한 통신 과정을 볼 수 있어 문제의 원인을 파악하는 데 큰 도움이 됩니다. 예를 들어, 다음과 같이 사용합니다.
curl -v -X POST -H "Content-Type: application/json" -d '{"key": "value"}' https://api.example.com/resource이 옵션을 통해 서버가 어떤 헤더를 받았는지, 어떤 응답 코드를 반환했는지 등을 상세히 확인할 수 있습니다. 특히 인증 관련 문제나 서버 설정 오류를 진단할 때 빛을 발합니다.
파일 전송의 모든 것: 업로드와 다운로드
curl 명령어 실전 활용 예시
curl은 파일을 서버로 업로드하거나 서버에서 다운로드하는 데에도 강력한 기능을 제공합니다. 파일을 다운로드할 때는 `-O` (대문자 오) 또는 `-o` (소문자 오) 옵션을 사용합니다. `-O` 옵션은 다운로드될 파일의 이름을 원본 URL의 파일명과 동일하게 저장하고, `-o` 옵션은 사용자가 지정한 이름으로 저장합니다. 예를 들어, 이미지 파일을 다운로드하는 경우:
curl -O https://www.example.com/images/logo.png이 명령어는 `logo.png` 파일을 현재 디렉토리에 다운로드합니다. 만약 다운로드된 파일을 `my_company_logo.png`로 저장하고 싶다면 다음과 같이 `-o` 옵션을 사용합니다.
curl -o my_company_logo.png https://www.example.com/images/logo.png파일을 서버로 업로드할 때는 `-F` (form) 옵션을 사용합니다. 이는 주로 multipart/form-data 형식으로 파일을 전송할 때 사용되며, 파일뿐만 아니라 일반적인 폼 데이터와 함께 전송할 수 있습니다. 예를 들어, `upload.txt` 파일을 서버의 `/upload` 엔드포인트로 업로드하는 경우:
curl -F 'file=@upload.txt' https://api.example.com/upload여기서 `'file=@upload.txt'`는 폼 필드의 이름이 'file'이고, 값이 `upload.txt` 파일의 내용임을 나타냅니다. 만약 여러 파일을 동시에 업로드해야 한다면, 동일한 폼 필드 이름을 반복하여 사용할 수 있습니다. 예를 들어, `image1.jpg`와 `image2.png`를 업로드하는 경우:
curl -F 'images=@image1.jpg' -F 'images=@image2.png' https://api.example.com/upload/multiple이러한 파일 전송 기능은 웹 서버의 파일 업로드 기능을 테스트하거나, 대용량 파일을 클라우드 스토리지에 업로드하는 등의 작업에 매우 유용합니다. 특히, 대용량 파일 전송 시에는 `-C -` 옵션을 사용하여 중단된 전송을 이어받는 기능을 활용할 수 있습니다. 이는 네트워크 불안정으로 인해 전송이 실패했을 때 매우 유용하며, 총 전송 시간의 80% 이상을 절약할 수 있는 경우도 있습니다.
보안과 인증: 안전한 API 접근
대부분의 API는 보안을 위해 인증 및 권한 부여 메커니즘을 사용합니다. curl은 이러한 보안 요구사항을 충족시키기 위한 다양한 옵션을 제공합니다. 가장 일반적인 인증 방법 중 하나는 HTTP Basic Authentication이며, `-u` 옵션을 사용하여 사용자 이름과 비밀번호를 전달합니다.
curl -u username:password https://api.example.com/protected/resourceAPI 키를 헤더에 포함하여 인증하는 경우도 많습니다. 예를 들어, `X-API-Key`라는 헤더에 API 키를 담아 보내려면 `-H` 옵션을 사용합니다.
curl -H "X-API-Key: YOUR_API_KEY_HERE" https://api.example.com/dataOAuth 2.0과 같은 복잡한 인증 흐름을 처리해야 할 때는, 토큰을 발급받는 과정부터 직접 curl 명령어로 수행해야 할 수 있습니다. 예를 들어, 액세스 토큰을 얻기 위해 POST 요청을 보내고, 얻은 토큰을 후속 요청의 Authorization 헤더에 포함시키는 방식입니다. 이때, `jq`와 같은 JSON 파서 도구를 함께 사용하면 응답에서 토큰 값을 추출하기 용이합니다.
ACCESS_TOKEN=$(curl -s -X POST -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" https://auth.example.com/oauth/token | jq -r '.access_token')
curl -H "Authorization: Bearer $ACCESS_TOKEN" https://api.example.com/secure/dataSSL/TLS 인증서 관련 문제를 해결해야 할 때도 curl은 유용합니다. 자체 서명된 인증서를 사용하거나 만료된 인증서로 인해 연결이 실패하는 경우, `-k` 또는 `--insecure` 옵션을 사용하여 인증서 검증을 비활성화할 수 있습니다. 하지만 이 옵션은 보안에 취약하므로, 개발 및 테스트 환경에서만 제한적으로 사용하는 것이 좋습니다. Apple 지원 문서(support.apple.com)에 따르면, 보안 연결은 데이터 무결성과 기밀성을 보장하는 핵심 요소이므로, 가능한 항상 유효한 인증서를 사용해야 합니다.
고급 활용 팁과 트러블슈팅
curl은 단순히 요청을 보내는 것을 넘어, 다양한 고급 기능을 통해 복잡한 시나리오를 처리할 수 있습니다. 예를 들어, 여러 개의 요청을 파이프라인으로 연결하여 순차적으로 실행하거나, 특정 조건에 따라 요청을 분기하는 스크립트를 작성할 수 있습니다. 또한, `-L` 옵션을 사용하면 리다이렉션(HTTP 3xx 응답)을 자동으로 따라가 최종 목적지의 응답을 받을 수 있습니다. 이는 웹사이트의 URL이 변경되었거나, 특정 서비스가 다른 경로로 요청을 리다이렉트할 때 매우 유용합니다.
curl -L http://example.com/old-url네트워크 관련 문제를 진단할 때는 curl의 다양한 옵션이 빛을 발합니다. 연결 시간, 이름 해석 시간, SSL 핸드셰이크 시간 등 각 단계별 소요 시간을 측정하여 병목 지점을 파악할 수 있습니다. 이를 위해 `--connect-timeout`과 `--max-time` 옵션을 조합하여 사용할 수 있습니다. 예를 들어, 연결 시도는 최대 5초, 전체 요청 시간은 최대 30초로 제한하는 것은 일반적인 보안 설정입니다.
`curl -k` 옵션을 사용하여 SSL 인증서 검증을 비활성화하는 것은 보안에 매우 취약하므로, 프로덕션 환경에서는 절대 사용해서는 안 됩니다. 테스트 및 개발 환경에서만 제한적으로 사용하고, 가능하다면 올바른 인증서로 교체하는 것이 최선입니다.
curl을 사용하여 특정 헤더를 제외하거나, 특정 헤더의 값을 변경하는 것도 가능합니다. 이는 API의 특정 동작을 시뮬레이션하거나, 보안 테스트를 수행할 때 유용합니다. 예를 들어, `User-Agent` 헤더를 변경하여 특정 브라우저에서 접근하는 것처럼 보이게 할 수 있습니다.
curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" https://example.com또한, curl은 쿠키를 관리하는 기능도 제공합니다. `-c` 옵션으로 쿠키를 파일에 저장하고, `-b` 옵션으로 저장된 쿠키를 사용하여 요청을 보낼 수 있습니다. 이는 웹사이트 로그인 후 세션 정보를 유지하며 API를 호출해야 하는 경우에 필수적입니다.
"결론은 앤트로픽이 말하는 그 정도는 아니라고 합니다. 176,000줄 66만 단어를 스캔해서 5개의 취약점이 있다고보고했는데 3개는 환각, 1개는 버그 나머지 1개는 그렇게 치명적인 문제는 아니었다고 합니다." (출처: clien.net) 이처럼 복잡한 분석 결과도 curl을 이용한 데이터 수집 및 전송 과정을 통해 이루어질 수 있습니다. curl은 단순히 명령어를 실행하는 것을 넘어, 복잡한 데이터 파이프라인을 구축하는 데에도 핵심적인 역할을 합니다.
curl 명령어는 API 테스트, 파일 전송, 보안 인증 등 다양한 개발 작업에서 필수적인 도구입니다. GET, POST와 같은 기본 HTTP 메서드부터 파일 업로드/다운로드, 헤더 조작, 인증 처리까지, curl은 터미널 환경에서 강력하고 효율적인 솔루션을 제공합니다. 다양한 옵션을 숙지하고 실전 예제를 통해 익히면 개발 생산성을 크게 향상시킬 수 있습니다.
지금 바로 적용해 보세요.
자주 묻는 질문
Q. curl이 정확히 무엇인가요?
A. curl은 URL을 사용하여 데이터를 전송하는 명령줄 도구입니다. 주로 API 테스트, 웹사이트 정보 가져오기, 파일 다운로드 및 업로드 등 다양한 네트워크 통신 작업에 활용됩니다.
Q. curl로 API 요청을 보낼 때 가장 기본적인 방법은 무엇인가요?
A. 가장 기본적인 방법은 `curl [URL]` 형태로 요청을 보내는 것입니다. GET 요청은 별도의 옵션 없이 URL만 지정하면 되고, POST 요청의 경우 `-X POST` 옵션과 함께 `-d` 옵션으로 데이터를 함께 전달합니다.
Q. curl로 파일을 전송하려면 어떻게 해야 하나요?
A. 파일 업로드 시에는 `-F` 옵션을 사용합니다. 예를 들어 `curl -F 'file=@/path/to/your/file.txt' [URL]`과 같이 사용하여 파일을 전송할 수 있습니다. 파일 다운로드는 `curl -O [URL]` 또는 `curl -o [filename] [URL]` 명령어를 사용합니다.
Q. curl 명령어가 너무 복잡하게 느껴지는데, 좀 더 쉽게 사용하는 팁이 있을까요?
A. 처음에는 자주 사용하는 기본적인 옵션부터 익히는 것이 좋습니다. 예를 들어 `-I` (헤더만 보기), `-v` (상세 정보 보기), `-H` (커스텀 헤더 추가) 등의 옵션을 먼저 숙지하고, 필요에 따라 점차 고급 기능을 학습해나가면 효율적으로 사용할 수 있습니다.
함께 읽으면 좋은 글