프록시와 REST API 클라이언트 통합: Postman, Insomnia, cURL 및 HTTPie 설정 방법

API를 개발하고 테스트할 때 프록시 서버를 통해 요청을 보내야 할 필요가 자주 발생합니다. 이는 지리적 제한을 우회하거나, 다양한 지역에서 API의 동작을 테스트하거나, 익명성을 보장하거나, 데이터 센터 IP를 차단하는 서비스와 작업할 때 필요할 수 있습니다. 이 가이드에서는 인기 있는 REST API 클라이언트에서 프록시를 올바르게 설정하고 일반적인 오류를 피하는 방법을 살펴보겠습니다.

API 작업을 위한 네 가지 가장 인기 있는 도구를 살펴보겠습니다: Postman(대부분의 개발자에게 그래픽 인터페이스), Insomnia(편리한 UI를 갖춘 현대적인 대안), cURL(고전적인 명령줄 도구) 및 HTTPie(사람이 읽을 수 있는 구문을 가진 현대적인 CLI 클라이언트). 각 도구에 대한 코드 예제를 제공하고 구성의 특징을 설명하겠습니다.

API 작업에 적합한 프록시 유형

API 클라이언트에서 프록시를 설정하기 전에 어떤 유형의 프록시가 귀하의 작업에 적합한지 이해하는 것이 중요합니다. REST API 클라이언트는 두 가지 주요 프로토콜을 지원합니다: HTTP/HTTPS 및 SOCKS5. 선택은 특정 API의 요구 사항과 필요한 보안 수준에 따라 다릅니다.

HTTP/HTTPS 프록시는 HTTP 프로토콜 수준에서 작동하며 대부분의 REST API 요청에 적합합니다. 이들은 HTTP 트래픽의 구조를 이해하고 응답을 캐시하며 헤더를 수정할 수 있습니다. HTTPS 프록시는 클라이언트와 프록시 서버 간의 연결을 추가로 암호화하여 API 키나 인증 토큰과 같은 민감한 데이터를 전송할 때 중요합니다.

SOCKS5 프록시는 더 낮은 수준에서 작동하며 수정 없이 모든 유형의 트래픽을 전달합니다. 이들은 HTTP 프록시보다 느리지만 더 나은 익명성을 제공하며 API가 비표준 프로토콜을 사용하거나 연결의 완전한 투명성이 필요한 경우에 적합합니다. SOCKS5는 UDP 트래픽도 지원하지만 REST API에서는 드물게 필요합니다.

Postman에서 프록시 설정: 전역 및 로컬 설정

Postman은 REST API 작업을 위한 가장 인기 있는 그래픽 도구로, 수백만 명의 개발자가 사용하고 있습니다. 이 도구는 프록시 설정을 위한 두 가지 방법을 지원합니다: 전역 설정(모든 요청에 적용됨) 및 환경 수준 설정. 두 가지 옵션을 자세히 살펴보겠습니다.

Postman에서 전역 프록시 설정

전역 프록시 설정은 오른쪽 상단의 설정 아이콘(톱니바퀴 아이콘)에서 찾을 수 있습니다. 이 방법은 Postman의 모든 요청이 항상 동일한 프록시 서버를 통해 전송되도록 하려는 경우에 편리합니다. 단계별 지침은 다음과 같습니다:

1. Postman을 열고 오른쪽 상단의 설정 아이콘(톱니바퀴)을 클릭합니다.
2. "Proxy" 탭으로 이동합니다.
3. "Add a custom proxy configuration" 옵션을 활성화합니다.
4. 프록시 유형을 선택합니다: HTTP, HTTPS 또는 SOCKS5.
5. 프록시 서버 주소를 입력합니다(예: proxy.example.com).
6. 포트를 지정합니다(일반적으로 HTTP의 경우 8080, SOCKS5의 경우 1080).
7. 프록시가 인증을 요구하는 경우 "Proxy Auth"를 활성화하고 로그인/비밀번호를 입력합니다.
8. "Save"를 클릭하고 설정 창을 닫습니다.

이후 모든 Postman 요청은 지정된 프록시를 통해 자동으로 전송됩니다. 중요한 점은 Postman이 또한 telemetry를 전송하고 프록시를 통해 업데이트를 확인한다는 것입니다. 이는 추가 트래픽을 생성할 수 있습니다. 제한된 트래픽을 가진 프록시를 사용하는 경우 이를 고려해야 합니다.

환경 변수를 통한 프록시 설정

더 유연한 방법은 환경 변수를 사용하는 것입니다. 이를 통해 다양한 프로젝트나 API에 대해 서로 다른 프록시 간에 빠르게 전환할 수 있습니다. 새 환경을 만들고 다음 변수를 추가합니다:

PROXY_HOST = proxy.example.com
PROXY_PORT = 8080
PROXY_USER = your_username
PROXY_PASS = your_password

그런 다음 전역 프록시 설정에서 특정 값 대신 이러한 변수를 사용합니다: {{PROXY_HOST}} 및 {{PROXY_PORT}}. 이제 여러 환경(예: "Production Proxy", "Testing Proxy", "US Proxy")을 만들고 클릭 한 번으로 전환할 수 있습니다.

시스템 프록시 사용

Postman은 또한 운영 체제의 시스템 프록시 설정을 사용할 수 있습니다. 이를 위해 프록시 설정에서 "Use System Proxy" 옵션을 선택합니다. 이는 이미 OS 수준에서 프록시를 설정한 경우(예: Windows 또는 macOS 설정을 통해) Postman이 브라우저와 동일한 설정을 사용하도록 하려는 경우에 편리합니다.

Insomnia에서 프록시 구성

Insomnia는 깔끔한 인터페이스와 오픈 소스의 현대적인 Postman 대안입니다. Insomnia에서 프록시 설정은 Postman과 약간 다르며 구성 파일을 편집하거나 환경 변수를 사용해야 합니다. 두 가지 방법을 모두 살펴보겠습니다.

환경 변수를 통한 설정

Insomnia에서 프록시를 설정하는 가장 간단한 방법은 표준 환경 변수 HTTP_PROXY 및 HTTPS_PROXY를 사용하는 것입니다. Insomnia는 이 변수를 시스템에서 자동으로 읽습니다. Insomnia를 실행하기 전에 설정하세요:

Linux/macOS:

export HTTP_PROXY="http://username:password@proxy.example.com:8080"
export HTTPS_PROXY="http://username:password@proxy.example.com:8080"
insomnia

Windows (PowerShell):

$env:HTTP_PROXY = "http://username:password@proxy.example.com:8080"
$env:HTTPS_PROXY = "http://username:password@proxy.example.com:8080"
insomnia

URL 형식에 유의하세요: HTTPS 프록시의 경우에도 http:// 스킴을 사용하고 https://를 사용하지 않습니다. 이는 프록시 환경 변수에 대한 표준 규칙입니다. 프록시가 인증을 요구하지 않는 경우 URL은 더 짧습니다: http://proxy.example.com:8080.

SOCKS5 프록시 설정

SOCKS5 프록시의 경우 ALL_PROXY 환경 변수를 사용하세요:

export ALL_PROXY="socks5://username:password@proxy.example.com:1080"

Insomnia는 SOCKS5를 지원하지만 모든 버전이 SOCKS5 인증을 올바르게 처리하지는 않습니다. 인증된 SOCKS5에 문제가 발생하면 HTTP 프록시를 사용하거나 Insomnia를 최신 버전으로 업데이트해 보세요.

구성 파일을 통한 설정

프록시를 지속적으로 설정하려면 Insomnia의 구성 파일을 편집할 수 있습니다. 파일의 위치는 운영 체제에 따라 다릅니다:

• Windows: %APPDATA%\Insomnia\config.json
• macOS: ~/Library/Application Support/Insomnia/config.json
• Linux: ~/.config/Insomnia/config.json

텍스트 편집기로 파일을 열고 proxy 섹션을 추가합니다:

{
  "proxy": {
    "http": "http://username:password@proxy.example.com:8080",
    "https": "http://username:password@proxy.example.com:8080"
  }
}

편집 후 Insomnia를 재시작하세요. 프록시 설정이 모든 요청에 자동으로 적용됩니다.

cURL에서 프록시 사용: 명령 예제

cURL은 HTTP 작업을 위한 고전적인 명령줄 도구로, 거의 모든 Unix 유사 시스템과 Windows 10+에 설치되어 있습니다. 이 도구는 -x 또는 --proxy 매개변수를 통해 프록시를 지원합니다. 다양한 사용 시나리오를 살펴보겠습니다.

HTTP 프록시 기본 사용

인증 없이 HTTP 프록시를 사용하는 가장 간단한 예제입니다:

curl -x http://proxy.example.com:8080 https://api.example.com/users

-x 매개변수는 프록시 서버의 주소와 포트를 지정합니다. cURL은 자동으로 이것이 HTTP 프록시임을 인식하고 연결을 설정합니다. 프로토콜을 명시적으로 지정하려면 전체 URL을 사용하세요:

curl --proxy http://proxy.example.com:8080 https://api.example.com/users

인증이 필요한 프록시

프록시가 로그인 및 비밀번호 인증을 요구하는 경우 URL 프록시에 추가하거나 -U 매개변수를 사용하세요:

# 방법 1: URL에 로그인 및 비밀번호 포함
curl -x http://username:password@proxy.example.com:8080 https://api.example.com/users

# 방법 2: -U 매개변수 사용(더 안전하며, 명령 기록에 저장되지 않음)
curl -x http://proxy.example.com:8080 -U username:password https://api.example.com/users

두 번째 방법이 더 바람직합니다. 왜냐하면 로그인과 비밀번호가 shell 명령 기록에 남지 않기 때문입니다. 더 높은 보안을 위해 로그인만 지정하고 cURL이 대화식으로 비밀번호를 요청하도록 할 수 있습니다:

curl -x http://proxy.example.com:8080 -U username https://api.example.com/users
# cURL이 비밀번호를 요청합니다: Enter proxy password for user 'username':

SOCKS5 프록시 사용

SOCKS5 프록시의 경우 URL에 프로토콜을 명시적으로 지정하세요:

# 인증 없는 SOCKS5
curl -x socks5://proxy.example.com:1080 https://api.example.com/users

# 인증이 필요한 SOCKS5
curl -x socks5://username:password@proxy.example.com:1080 https://api.example.com/users

# SOCKS5h (프록시를 통한 DNS 해상도)
curl -x socks5h://proxy.example.com:1080 https://api.example.com/users

socks5://와 socks5h://의 차이점: 첫 번째 경우 DNS 해상도가 로컬(귀하의 머신)에서 발생하고, 두 번째 경우는 프록시 서버를 통해 발생합니다. DNS 요청을 제공업체로부터 완전히 숨기고 싶다면 socks5h://를 사용하세요.

프록시를 통한 POST 요청

프록시는 모든 HTTP 메서드에 대해 동일하게 작동합니다. 프록시를 통한 JSON 데이터의 POST 요청 예제입니다:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}' \
  https://api.example.com/users

파일을 전송하려면 -F 매개변수를 사용하세요:

curl -x http://proxy.example.com:8080 \
  -X POST \
  -F "file=@document.pdf" \
  -F "description=Important document" \
  https://api.example.com/upload

환경 변수를 사용한 설정

각 명령에서 프록시를 지정하는 대신 환경 변수를 사용할 수 있습니다. cURL은 자동으로 http_proxy, https_proxy 및 all_proxy를 읽습니다:

# 환경 변수 설정
export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"

# 이제 모든 cURL 명령이 자동으로 프록시를 사용합니다
curl https://api.example.com/users

# 특정 명령에 대해 프록시를 비활성화하려면
curl --noproxy "*" https://api.example.com/users

--noproxy 매개변수는 특정 도메인을 프록시에서 제외할 수 있습니다. 예를 들어, localhost 및 내부 도메인에 대해 프록시를 사용하지 않으려면:

export no_proxy="localhost,127.0.0.1,.internal.company.com"

HTTPie에서 프록시 설정

HTTPie는 사람 읽을 수 있는 구문과 색상 출력을 가진 현대적인 cURL 대안입니다. 이 도구는 터미널에서 API와 상호작용할 때 특히 편리합니다. HTTPie는 --proxy 매개변수 또는 환경 변수를 통해 프록시를 지원합니다.

프록시 기본 사용

HTTPie의 프록시 구문은 cURL과 약간 다릅니다. 프로토콜과 프록시 URL을 별도로 지정해야 합니다:

# HTTP 프록시
http --proxy=http:http://proxy.example.com:8080 \
     --proxy=https:http://proxy.example.com:8080 \
     GET https://api.example.com/users

# 축약형(HTTP와 HTTPS 프록시가 동일한 경우)
http --proxy=all:http://proxy.example.com:8080 GET https://api.example.com/users

형식: --proxy=protocol:proxy_url. HTTPS 요청의 경우 일반적으로 HTTP 프록시(HTTPS 아님)를 사용합니다. 이는 표준 동작입니다.

인증이 필요한 프록시

인증을 위해 로그인과 비밀번호를 프록시 URL에 추가하세요:

http --proxy=all:http://username:password@proxy.example.com:8080 \
     GET https://api.example.com/users

HTTPie는 또한 더 명시적으로 자격 증명을 지정하기 위한 --proxy-auth 매개변수를 지원하지만, 최신 버전에서는 이 매개변수가 더 이상 권장되지 않으며, URL에 인증을 포함하는 것이 좋습니다.

HTTPie에서 SOCKS5 프록시 사용

HTTPie는 2.0.0 버전부터 SOCKS5 프록시를 지원합니다. 최신 버전이 설치되어 있는지 확인하세요:

# HTTPie 버전 확인
http --version

# pip를 통해 HTTPie 업데이트
pip install --upgrade httpie

# SOCKS5 프록시 사용
http --proxy=all:socks5://proxy.example.com:1080 GET https://api.example.com/users

인증이 필요한 SOCKS5의 경우 추가 라이브러리 pysocks를 설치해야 합니다:

pip install pysocks
http --proxy=all:socks5://username:password@proxy.example.com:1080 \
     GET https://api.example.com/users

POST 요청 및 데이터 전송

HTTPie는 POST 요청에 대한 편리한 구문을 제공합니다. 프록시를 통한 JSON 전송 예제입니다:

# JSON으로 POST (HTTPie가 Content-Type을 자동으로 결정함)
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/users \
     name="John Doe" \
     email="john@example.com" \
     age:=30

# 파일 전송
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/upload \
     file@document.pdf \
     description="Important document"

구문에 유의하세요: key=value는 문자열, key:=value는 숫자 및 불리언 값, key@file는 파일을 나타냅니다.

환경 변수를 사용한 설정

cURL과 마찬가지로 HTTPie는 표준 환경 변수 http_proxy 및 https_proxy를 읽습니다:

export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"

# 이제 모든 명령이 자동으로 프록시를 사용합니다
http GET https://api.example.com/users

프록시를 일시적으로 비활성화하려면 --proxy=(빈 값)를 사용하세요:

http --proxy= GET https://api.example.com/users

프록시 인증: 로그인 및 비밀번호

대부분의 상업용 프록시 서비스는 무단 사용을 방지하기 위해 인증을 요구합니다. 인증에는 두 가지 주요 방법이 있습니다: Basic Authentication(로그인/비밀번호) 및 IP Whitelist(IP 주소에 대한 화이트리스트). 각 방법의 특징과 API 클라이언트에서 올바르게 설정하는 방법을 살펴보겠습니다.

Basic Authentication (로그인 및 비밀번호)

Basic Authentication은 가장 일반적인 방법입니다. 프록시 서버는 연결 시마다 로그인과 비밀번호를 요구합니다. 자격 증명은 Base64 형식으로 Proxy-Authorization 헤더에 전달됩니다. 모든 현대 API 클라이언트는 프록시 URL에 로그인과 비밀번호를 지정하면 이 헤더를 자동으로 생성합니다.

인증이 포함된 URL 형식:

protocol://username:password@proxy_host:proxy_port

다양한 프로토콜에 대한 예:

# HTTP 프록시
http://user123:pass456@proxy.example.com:8080

# HTTPS 프록시 (동일한 형식 사용)
http://user123:pass456@proxy.example.com:8080

# SOCKS5 프록시
socks5://user123:pass456@proxy.example.com:1080

IP Whitelist (IP 주소에 대한 화이트리스트)

일부 프록시 제공업체는 IP 주소에 대한 인증을 제공합니다. 이 경우 귀하의 IP를 프록시 관리 패널의 화이트리스트에 추가하고 서버는 로그인 및 비밀번호 없이 해당 IP에서의 연결만 허용합니다. 이는 더 편리하고 안전합니다. 왜냐하면 각 요청에 자격 증명을 전달할 필요가 없기 때문입니다.

IP Whitelist를 사용할 경우 프록시 URL 형식이 간단해집니다:

# 로그인 및 비밀번호 없이
http://proxy.example.com:8080

# cURL 예제
curl -x http://proxy.example.com:8080 https://api.example.com/users

이 방법의 단점은 IP가 동적일 경우(인터넷에 재연결할 때 변경됨) 매번 화이트리스트를 업데이트해야 한다는 것입니다. 정적 IP를 가진 서버에는 이상적인 옵션입니다.

비밀번호의 특수 문자

프록시 비밀번호에 특수 문자가 포함된 경우(@, :, /, ?), URL 인코딩(퍼센트 인코딩) 형식으로 인코딩해야 합니다. 예를 들어:

특수 문자가 포함된 비밀번호 사용 예제:

# 원래 비밀번호: P@ss:w0rd/123
# 인코딩된 비밀번호: P%40ss%3Aw0rd%2F123

curl -x http://username:P%40ss%3Aw0rd%2F123@proxy.example.com:8080 \
     https://api.example.com/users

자동 인코딩을 위해 온라인 URL 인코더 도구를 사용하거나 Python에서 다음 명령을 사용할 수 있습니다:

python3 -c "import urllib.parse; print(urllib.parse.quote('P@ss:w0rd/123'))"
# 출력: P%40ss%3Aw0rd%2F123

일반적인 문제 및 오류 해결

API 클라이언트에서 프록시 작업 시 일반적인 오류가 자주 발생합니다. 가장 흔한 문제와 해결 방법을 살펴보겠습니다.

"407 Proxy Authentication Required" 오류

이 오류는 프록시 서버가 인증을 요구하지만 자격 증명이 제공되지 않았거나 잘못되었음을 의미합니다. 해결 방법:

• 프록시 제공업체의 관리 패널에서 로그인 및 비밀번호의 정확성을 확인하세요.
• 비밀번호의 특수 문자가 인코딩되었는지 확인하세요(위의 섹션 참조).
• URL 형식을 확인하세요: http://username:password@host:port.
• IP Whitelist를 사용하는 경우 현재 IP가 화이트리스트에 추가되었는지 확인하세요.

cURL에서 자세한 출력을 통해 진단하는 예제:

curl -v -x http://username:password@proxy.example.com:8080 https://api.example.com/users
# -v (verbose) 플래그는 모든 헤더와 인증 과정을 보여줍니다.

"Connection timeout" 또는 "Failed to connect" 오류

이 오류는 API 클라이언트가 프록시 서버와 연결할 수 없을 때 발생합니다. 가능한 원인:

• 프록시 서버의 주소 또는 포트가 잘못되었습니다 — 제공업체의 설정을 확인하세요.
• 프록시 서버가 사용할 수 없거나 과부하 상태입니다 — 목록에서 다른 서버를 시도해 보세요.
• 방화벽이 프록시 포트에 대한 아웃바운드 연결을 차단하고 있습니다.
• 프록시 제공업체가 IP를 제한하여 차단했습니다.

진단을 위해 telnet 또는 nc를 통해 프록시에 직접 연결해 보세요:

# 프록시의 가용성 확인
telnet proxy.example.com 8080
# 또는
nc -zv proxy.example.com 8080

# 연결이 설정되지 않으면 네트워크 문제이거나 프록시 서버가 사용할 수 없습니다.

"SSL certificate problem" 오류

HTTPS 프록시를 사용할 때 SSL 인증서 확인에 문제가 발생할 수 있습니다. 이는 MITM(Man-in-the-Middle) 프록시가 HTTPS 트래픽을 가로채고 해독하는 경우 특히 관련이 있습니다. 해결 방법:

• cURL에서 -k 또는 --insecure 플래그를 사용하여 인증서 검사를 비활성화하세요(테스트 용도만 사용!).
• Postman에서 Settings → General에서 "SSL certificate verification"을 비활성화하세요.
• 프로덕션 환경에서는 프록시의 루트 인증서를 시스템에 설치하세요.

# 인증서 확인 비활성화
curl -k -x http://proxy.example.com:8080 https://api.example.com/users

위의 방법으로도 문제가 해결되지 않으면 프록시 제공업체에 문의하여 추가 지원을 받으세요.