Proxy'nin REST API Müşterileri ile Entegrasyonu: Postman, Insomnia, cURL ve HTTPie Ayarları

API geliştirme ve test etme sırasında sıklıkla proxy sunucuları üzerinden istek göndermeye ihtiyaç duyulur. Bu, coğrafi kısıtlamaları aşmak, API'nin farklı bölgelerden davranışını test etmek, anonimlik sağlamak veya IP veri merkezlerini engelleyen hizmetlerle çalışmak için gerekebilir. Bu kılavuzda, popüler REST API istemcilerinde proxy ayarlarını nasıl doğru bir şekilde yapacağınızı ve yaygın hatalardan nasıl kaçınacağınızı inceleyeceğiz.

API ile çalışmak için en popüler dört aracı inceleyeceğiz: Postman (çoğu geliştirici için grafik arayüz), Insomnia (kullanışlı UI ile modern bir alternatif), cURL (klasik komut satırı aracı) ve HTTPie (insan okunabilir sözdizimi ile modern bir CLI istemcisi). Her araç için kod örnekleri sunacağız ve yapılandırma özelliklerini ele alacağız.

API ile çalışmak için hangi proxy türleri uygundur

API istemcilerinde proxy ayarlamadan önce, hangi proxy türünün işinize yarayacağını anlamak önemlidir. REST API istemcileri iki ana protokolü destekler: HTTP/HTTPS ve SOCKS5. Seçim, belirli bir API'nin gereksinimlerine ve ihtiyaç duyduğunuz güvenlik seviyesine bağlıdır.

HTTP/HTTPS proxy'leri HTTP protokolü seviyesinde çalışır ve çoğu REST API isteği için idealdir. HTTP trafiğinin yapısını anlayabilir, yanıtları önbelleğe alabilir ve başlıkları değiştirebilirler. HTTPS proxy'leri, istemci ile proxy sunucusu arasındaki bağlantıyı ek olarak şifreler; bu, API anahtarları veya kimlik doğrulama token'ları gibi hassas verilerin iletilmesi sırasında önemlidir.

SOCKS5 proxy'leri daha düşük bir seviyede çalışır ve herhangi bir türde trafiği değiştirmeden iletebilir. HTTP proxy'lerinden daha yavaştırlar, ancak daha iyi anonimlik sağlarlar ve API'nin standart dışı protokoller kullandığı veya bağlantının tamamen şeffaf olmasının gerektiği durumlar için uygundur. SOCKS5 ayrıca UDP trafiğini de destekler, ancak REST API için bu nadiren gereklidir.

Postman'da proxy ayarları: küresel ve yerel ayarlar

Postman — REST API ile çalışmak için en popüler grafik aracıdır ve milyonlarca geliştirici tarafından kullanılmaktadır. İki proxy ayarlama yöntemi destekler: küresel ayarlar (tüm isteklere uygulanır) ve ortam düzeyindeki ayarlar. Her iki seçeneği de ayrıntılı olarak inceleyeceğiz.

Postman'da küresel proxy ayarı

Küresel proxy ayarları, Ayarlar menüsünde (sağ üst köşedeki dişli simgesi) bulunur. Bu yöntem, Postman'dan gelen tüm isteklerin her zaman aynı proxy sunucusu üzerinden geçmesini istediğinizde kullanışlıdır. Adım adım talimat:

1. Postman'ı açın ve sağ üst köşedeki dişli simgesine (Ayarlar) tıklayın
2. "Proxy" sekmesine gidin
3. "Add a custom proxy configuration" seçeneğini etkinleştirin
4. Proxy türünü seçin: HTTP, HTTPS veya SOCKS5
5. Proxy sunucusunun adresini girin (örneğin: proxy.example.com)
6. Portu belirtin (genellikle HTTP için 8080, SOCKS5 için 1080)
7. Eğer proxy kimlik doğrulaması gerekiyorsa, "Proxy Auth" seçeneğini etkinleştirin ve kullanıcı adı/şifre girin
8. "Save" butonuna tıklayın ve ayarlar penceresini kapatın

Bundan sonra, Postman'dan gelen tüm istekler otomatik olarak belirtilen proxy üzerinden geçecektir. Önemli bir özellik: Postman ayrıca telemetri gönderir ve güncellemeleri proxy üzerinden kontrol eder, bu da ek trafik oluşturabilir. Sınırlı trafik olan bir proxy kullanıyorsanız, bunu göz önünde bulundurmalısınız.

Proxy ayarlarının ortam değişkenleri ile yapılması

Daha esnek bir yöntem, ortam değişkenlerini (Environments) kullanmaktır. Bu, farklı projeler veya API'ler için farklı proxy'ler arasında hızlı bir şekilde geçiş yapmanızı sağlar. Yeni bir ortam oluşturun ve aşağıdaki değişkenleri ekleyin:

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

Ardından, küresel proxy ayarlarında bu değişkenleri belirli değerler yerine kullanın: {{PROXY_HOST}} ve {{PROXY_PORT}}. Artık birden fazla ortam oluşturabilirsiniz (örneğin, "Production Proxy", "Testing Proxy", "US Proxy") ve bunlar arasında tek bir tıklama ile geçiş yapabilirsiniz.

Sistem proxy'sinin kullanımı

Postman ayrıca işletim sisteminizin sistem proxy ayarlarını kullanabilir. Bunun için Proxy ayarlarında "Use System Proxy" seçeneğini seçin. Bu, işletim sistemi düzeyinde (örneğin, Windows veya macOS ayarları aracılığıyla) proxy ayarlarını zaten yaptıysanız ve Postman'ın tarayıcıyla aynı ayarları kullanmasını istiyorsanız kullanışlıdır.

Insomnia'da proxy yapılandırması

Insomnia — temiz bir arayüze ve açık kaynak koduna sahip modern bir Postman alternatifidir. Insomnia'da proxy ayarları, Postman'dan biraz farklıdır ve yapılandırma dosyasını düzenlemeyi veya ortam değişkenlerini kullanmayı gerektirir. Her iki yöntemi de inceleyelim.

Ortam değişkenleri ile yapılandırma

Insomnia'da proxy ayarlamanın en basit yolu, standart HTTP_PROXY ve HTTPS_PROXY ortam değişkenlerini kullanmaktır. Insomnia, bu değişkenleri sistemden otomatik olarak okur. Bunları Insomnia'yı başlatmadan önce ayarlayın:

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 formatına dikkat edin: HTTPS proxy için bile http:// şeması kullanılır, https:// değil. Bu, proxy ortam değişkenleri için standart bir anlaşmadır. Eğer proxy kimlik doğrulaması gerektirmiyorsa, URL daha kısa olacaktır: http://proxy.example.com:8080.

SOCKS5 proxy ayarları

SOCKS5 proxy için ALL_PROXY ortam değişkenini kullanın:

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

Insomnia SOCKS5'i destekler, ancak tüm sürümler SOCKS5 kimlik doğrulamasını doğru bir şekilde işleyemez. Eğer kimlik doğrulamalı SOCKS5 ile sorun yaşıyorsanız, HTTP proxy kullanmayı deneyin veya Insomnia'yı en son sürüme güncelleyin.

Yapılandırma dosyası ile ayarlama

Proxy'yi kalıcı olarak ayarlamak için Insomnia yapılandırma dosyasını düzenleyebilirsiniz. Dosyanın yeri işletim sistemine bağlıdır:

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

Dosyayı bir metin düzenleyicisinde açın ve proxy bölümünü ekleyin:

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

Düzenledikten sonra Insomnia'yı yeniden başlatın. Proxy ayarları tüm isteklere otomatik olarak uygulanacaktır.

cURL'de proxy kullanımı: komut örnekleri

cURL — HTTP ile çalışmak için klasik bir komut satırı aracıdır ve neredeyse tüm Unix benzeri sistemlerde ve Windows 10+ üzerinde yüklüdür. Proxy'leri -x veya --proxy parametresi ile destekler. Farklı kullanım senaryolarını inceleyelim.

Temel HTTP proxy kullanımı

Kimlik doğrulaması gerektirmeyen HTTP proxy kullanımı için en basit örnek:

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

-x parametresi proxy sunucusunun adresini ve portunu belirtir. cURL otomatik olarak bunun bir HTTP proxy olduğunu belirleyecek ve bağlantıyı ayarlayacaktır. Protokolü açıkça belirtmek isterseniz, tam URL'yi kullanın:

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

Kimlik doğrulamalı proxy

Eğer proxy, kullanıcı adı ve şifre ile kimlik doğrulaması gerektiriyorsa, bunları proxy URL'sine ekleyin veya -U parametresini kullanın:

# Yöntem 1: URL'de kullanıcı adı ve şifre
curl -x http://username:password@proxy.example.com:8080 https://api.example.com/users

# Yöntem 2: -U parametresi (daha güvenli, komut geçmişine kaydedilmez)
curl -x http://proxy.example.com:8080 -U username:password https://api.example.com/users

İkinci yöntem tercih edilir, çünkü kullanıcı adı ve şifre shell komut geçmişine kaydedilmez. Daha fazla güvenlik için yalnızca kullanıcı adını belirtebilir ve cURL, şifreyi etkileşimli olarak isteyecektir:

curl -x http://proxy.example.com:8080 -U username https://api.example.com/users
# cURL şifreyi isteyecek: Enter proxy password for user 'username':

SOCKS5 proxy kullanımı

SOCKS5 proxy için URL'de protokolü açıkça belirtin:

# SOCKS5 kimlik doğrulaması olmadan
curl -x socks5://proxy.example.com:1080 https://api.example.com/users

# SOCKS5 kimlik doğrulaması ile
curl -x socks5://username:password@proxy.example.com:1080 https://api.example.com/users

# SOCKS5h (DNS çözümlemesi proxy üzerinden)
curl -x socks5h://proxy.example.com:1080 https://api.example.com/users

socks5:// ve socks5h:// arasındaki fark: birincisinde DNS çözümlemesi yerel olarak (makinenizde) gerçekleşirken, ikincisinde proxy sunucusu üzerinden gerçekleşir. DNS isteklerinizi sağlayıcınızdan tamamen gizlemek istiyorsanız socks5h:// kullanın.

Proxy üzerinden POST istekleri

Proxy, tüm HTTP yöntemleri için aynı şekilde çalışır. Proxy üzerinden JSON verileri ile bir POST isteği örneği:

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

Dosya göndermek için -F parametresini kullanın:

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

Ortam değişkenlerinin kullanımı

Her komutta proxy belirtmek yerine ortam değişkenlerini kullanabilirsiniz. cURL otomatik olarak http_proxy, https_proxy ve all_proxy değişkenlerini okur:

# Ortam değişkenlerini ayarlayın
export http_proxy="http://username:password@proxy.example.com:8080"
export https_proxy="http://username:password@proxy.example.com:8080"

# Artık tüm cURL komutları otomatik olarak proxy kullanır
curl https://api.example.com/users

# Belirli bir komut için proxy'yi devre dışı bırakmak için
curl --noproxy "*" https://api.example.com/users

--noproxy parametresi, belirli alan adlarını proxy'den hariç tutmanıza olanak tanır. Örneğin, localhost ve dahili alan adları için proxy kullanmamak üzere:

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

HTTPie'da proxy ayarları

HTTPie — insan okunabilir sözdizimi ve renkli çıktı ile modern bir cURL alternatifidir. Terminalde API ile etkileşimli çalışmak için özellikle kullanışlıdır. HTTPie, proxy'leri --proxy parametresi veya ortam değişkenleri aracılığıyla destekler.

Proxy'nin temel kullanımı

HTTPie için proxy sözdizimi, cURL'den biraz farklıdır. Protokolü ve proxy URL'sini ayrı olarak belirtmek gerekir:

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

# Kısa form (eğer proxy HTTP ve HTTPS için aynı ise)
http --proxy=all:http://proxy.example.com:8080 GET https://api.example.com/users

Format: --proxy=protokol:proxy_url. HTTPS istekleri için genellikle HTTP proxy (HTTPS değil) kullanılır, bu standart bir davranıştır.

Kimlik doğrulamalı proxy

Kimlik doğrulaması için, proxy URL'sine kullanıcı adı ve şifre ekleyin:

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

HTTPie ayrıca daha belirgin bir şekilde kimlik bilgilerini belirtmek için --proxy-auth parametresini destekler, ancak son sürümlerde bu parametre geçersiz sayılmakta ve kimlik doğrulamanın URL'de belirtilmesi önerilmektedir.

HTTPie'da SOCKS5 proxy

HTTPie, 2.0.0 sürümünden itibaren SOCKS5 proxy'yi desteklemektedir. Güncel bir sürüm kullandığınızdan emin olun:

# HTTPie sürümünü kontrol et
http --version

# HTTPie'yi pip ile güncelle
pip install --upgrade httpie

# SOCKS5 proxy kullan
http --proxy=all:socks5://proxy.example.com:1080 GET https://api.example.com/users

Kimlik doğrulamalı SOCKS5 için ek bir kütüphane olan pysocks'ı yüklemeniz gerekecektir:

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

POST istekleri ve veri gönderimi

HTTPie, POST istekleri için kullanışlı bir sözdizimine sahiptir. Proxy üzerinden JSON gönderimi örneği:

# JSON ile POST (HTTPie otomatik olarak Content-Type'ı belirler)
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/users \
     name="John Doe" \
     email="john@example.com" \
     age:=30

# Dosya gönderimi
http --proxy=all:http://proxy.example.com:8080 \
     POST https://api.example.com/upload \
     file@document.pdf \
     description="Important document"

Sözdizimine dikkat edin: key=value dizeleri için, key:=value sayılar ve boolean değerler için, key@file dosyalar için.

Ortam değişkenlerinin kullanımı

cURL gibi, HTTPie de standart ortam değişkenlerini http_proxy ve https_proxy okur:

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

# Artık tüm komutlar otomatik olarak proxy kullanır
http GET https://api.example.com/users

Proxy'yi geçici olarak devre dışı bırakmak için --proxy= (boş değer) parametresini kullanın:

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

Proxy kimlik doğrulaması: kullanıcı adı ve şifre

Çoğu ticari proxy hizmeti, yetkisiz kullanımı önlemek için kimlik doğrulaması gerektirir. İki ana kimlik doğrulama yöntemi vardır: Temel Kimlik Doğrulama (kullanıcı adı/şifre) ve IP Beyaz Listesi (IP adresine bağlama). Her yöntemin özelliklerini ve API istemcilerinde nasıl doğru bir şekilde ayarlanacağını inceleyelim.

Temel Kimlik Doğrulama (kullanıcı adı ve şifre)

Temel Kimlik Doğrulama — en yaygın yöntemdir. Proxy sunucusu, her bağlantıda kullanıcı adı ve şifre ister. Kimlik bilgileri, Proxy-Authorization başlığında Base64 formatında iletilir. Tüm modern API istemcileri, proxy URL'sinde kullanıcı adı ve şifre belirttiğinizde bu başlığı otomatik olarak oluşturur.

Kimlik doğrulamalı URL formatı:

protokol://kullanıcı_adı:şifre@proxy_host:proxy_port

Farklı protokoller için örnekler:

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

# HTTPS proxy (aynı format kullanılır)
http://user123:pass456@proxy.example.com:8080

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

IP Beyaz Listesi (IP'ye bağlama)

Bazı proxy sağlayıcıları, IP adresine göre kimlik doğrulaması sunar. Bu durumda, proxy kontrol panelinde IP'nizi beyaz listeye ekleyerek, sunucu yalnızca bu IP'den gelen bağlantılara izin verir; kullanıcı adı ve şifre gerekmez. Bu, daha pratik ve güvenli bir yöntemdir, çünkü her istekte kimlik bilgilerini iletmek zorunda kalmazsınız.

IP Beyaz Listesi kullanırken, proxy URL'sinin formatı basitleşir:

# Kullanıcı adı ve şifre olmadan
http://proxy.example.com:8080

# cURL'de örnek
curl -x http://proxy.example.com:8080 https://api.example.com/users

Bu yöntemin dezavantajı, IP'niz dinamikse (internete yeniden bağlandığınızda değişiyorsa), her seferinde beyaz listeyi güncellemeniz gerekecektir. Statik IP'ye sahip sunucular için bu ideal bir seçenektir.

Şifrede özel karakterler

Eğer proxy şifresi özel karakterler içeriyorsa (@, :, /, ?), bunları URL kodlama (percent encoding) formatında kodlamanız gerekir. Örneğin:

Özel karakterler içeren bir şifre kullanımı örneği:

# Orijinal şifre: P@ss:w0rd/123
# Kodlanmış şifre: P%40ss%3Aw0rd%2F123

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

Otomatik kodlama için çevrimiçi URL kodlayıcı araçları veya Python'da bir komut kullanabilirsiniz:

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

Yaygın sorunlar ve hataların çözümü

Proxy ile API istemcileri kullanırken sıkça karşılaşılan yaygın hatalar vardır. En yaygın sorunları ve bunların nasıl çözüleceğini inceleyelim.

"407 Proxy Authentication Required" hatası

Bu hata, proxy sunucusunun kimlik doğrulaması gerektirdiğini, ancak kimlik bilgilerinin sağlanmadığını veya yanlış olduğunu gösterir. Çözümler:

• Proxy sağlayıcısının kontrol panelinde kullanıcı adı ve şifrenizin doğruluğunu kontrol edin
• Şifredeki özel karakterlerin kodlandığından emin olun (yukarıdaki bölüme bakın)
• URL formatını kontrol edin: http://username:password@host:port
• IP Beyaz Listesi kullanıyorsanız, mevcut IP'nizin beyaz listeye eklendiğinden emin olun

cURL'de ayrıntılı çıktı ile teşhis örneği:

curl -v -x http://username:password@proxy.example.com:8080 https://api.example.com/users
# -v (verbose) bayrağı, tüm başlıkları ve kimlik doğrulama sürecini gösterecektir

"Connection timeout" veya "Failed to connect" hatası

Bu hata, API istemcisinin proxy sunucusuyla bağlantı kuramadığını gösterir. Olası nedenler:

• Proxy sunucusunun adresi veya portu yanlış — sağlayıcı ayarlarını kontrol edin
• Proxy sunucusu erişilemez veya aşırı yüklenmiş — listedeki başka bir sunucuyu deneyin
• Güvenlik duvarınız, proxy portuna giden çıkış bağlantılarını engelliyor
• Proxy sağlayıcısı, limitleri aşmanız nedeniyle IP'nizi engelledi

Teşhis için, telnet veya nc ile proxy'ye doğrudan bağlanmayı deneyin:

# Proxy erişilebilirliğini kontrol et
telnet proxy.example.com 8080
# veya
nc -zv proxy.example.com 8080

# Eğer bağlantı kurulamazsa, sorun ağda veya proxy sunucusu erişilemezdir

"SSL certificate problem" hatası

HTTPS proxy kullanırken SSL sertifikalarının doğrulanmasında sorunlar yaşanabilir. Bu, özellikle HTTPS trafiğini yakalayan ve şifreleyen MITM (Man-in-the-Middle) proxy'leri için geçerlidir. Çözümler:

• cURL'de -k veya --insecure bayrağını kullanarak sertifika doğrulamasını devre dışı bırakın (sadece test için!)
• Postman'da "SSL certificate verification" seçeneğini Ayarlar → Genel bölümünde devre dışı bırakın
• Üretim ortamı için proxy'nin kök sertifikasını sisteme yükleyin

# Sertifika doğrulamasını devre dışı bırakma
curl -k -x http://username:password@proxy.example.com:8080 https://api.example.com/users

API istemcilerinde proxy ile çalışma en iyi uygulamaları

Proxy kullanırken dikkate almanız gereken bazı en iyi uygulamalar:

• Proxy ayarlarınızı gizli tutun; kullanıcı adı ve şifrelerinizi açık bir şekilde saklamayın.
• Proxy'yi test etmek için her zaman bir test ortamı kullanın.
• Proxy sağlayıcınızın güvenilir olduğundan emin olun; kötü bir proxy, verilerinizi tehlikeye atabilir.
• Proxy bağlantı hızını ve yanıt sürelerini izleyin; yavaş bir proxy, API performansınızı olumsuz etkileyebilir.
• Proxy ayarlarınızı gerektiğinde güncelleyin; IP adresleri değişebilir veya yeni güvenlik gereksinimleri ortaya çıkabilir.

Sonuç

Proxy kullanımı, API geliştirme ve test etme sürecinde önemli bir araçtır. Doğru yapılandırma ile, coğrafi kısıtlamaları aşabilir, anonim kalabilir ve IP engellemelerini aşabilirsiniz. Bu kılavuzda, popüler REST API istemcilerinde proxy ayarlarını nasıl yapacağınızı ve yaygın sorunları nasıl çözeceğinizi öğrendiniz. Unutmayın, her zaman güvenilir bir proxy sağlayıcısı seçin ve kimlik bilgilerinizi güvende tutun.