PHP ile otomasyon sistemleri kurarken API entegrasyonları işin olmazsa olmazı. Banka ödemeleri, kargo takibi, CRM senkronizasyonu, e-posta pazarlama araçları… Hepsi birer API. Doğru kullanılmadığında ise güvenlik açıklarına, performans sorunlarına ve bakım kabusuna dönüşebilir. Bu yazıda PHP otomasyon sistemlerinde API kullanımını uçtan uca ele alıyorum: temel kavramlar, kimlik doğrulama yöntemleri, hata yönetimi, performans iyileştirme ve güvenlik. Amacım, sadece çalışan değil, aynı zamanda sürdürülebilir ve ölçeklenebilir bir entegrasyon katmanı kurmanıza yardımcı olmak.

API Entegrasyonuna Başlarken: Neden PHP?

PHP, özellikle web tabanlı otomasyon sistemlerinde hâlâ en yaygın dillerden biri. Laravel, Symfony gibi olgun framework’ler, hazır HTTP istemcileri, güvenlik paketleri ve topluluk desteğiyle API entegrasyonunu hızlandırır. Ayrıca paylaşımlı hosting ortamlarında bile sorunsuz çalışabilmesi, küçük ve orta ölçekli projeler için büyük bir avantaj.

PHP ile API kullanırken iki temel senaryo vardır: harici bir servisin API’sini tüketmek (istemci tarafı) ve kendi sisteminizin API’sini sunmak (sunucu tarafı). Bu yazıda ağırlıklı olarak ilk senaryoyu ele alacağım; çünkü otomasyon sistemlerinin çoğu, dış dünyayla konuşan bir yapıya sahiptir.

API Nedir, Ne Değildir?

API (Application Programming Interface), iki yazılım arasındaki sözleşmedir. İsteklerin nasıl yapılacağını, verinin hangi formatta döneceğini, hata durumlarında ne beklenmesi gerektiğini tanımlar. REST ve GraphQL en yaygın mimariler olsa da, SOAP hâlâ bazı kurumsal sistemlerde karşımıza çıkar.

REST, kaynak odaklıdır; HTTP metodları (GET, POST, PUT, DELETE) ile çalışır. GraphQL ise tek bir uç noktadan ihtiyacınız olan alanları çekmenize izin verir. Otomasyon sisteminizde hangisinin daha uygun olduğuna karar verirken şunlara bakın: ekip deneyimi, veri ihtiyacının dinamikliği, mevcut altyapı.

PHP ile API İstekleri Nasıl Yapılır?

PHP’nin dosya fonksiyonlarıyla (file_get_contents) basit bir GET isteği yapmak mümkün olsa da, bu yöntem hata yönetimi, zaman aşımı ve HTTP durum kodları gibi konularda yetersizdir. Bu yüzden modern PHP projelerinde cURL veya Guzzle gibi HTTP istemcileri tercih edilir.

İşte Guzzle ile bir GET isteği örneği:

use GuzzleHttpClient;

$client = new Client(['base_uri' => 'https://api.ornek.com/v1/']);
$response = $client->get('musteriler', [
    'headers' => ['Authorization' => 'Bearer ' . $apiToken]
]);

$data = json_decode($response->getBody(), true);

Bu kodda dikkat edilmesi gereken nokta: base_uri ve timeout gibi ayarların merkezi bir yerde tanımlanmasıdır. Böylece farklı servisler için tekrarlayan istemci yapılandırmasından kaçınırsınız.

Kimlik Doğrulama: Temel, API Anahtarı, OAuth 2.0

API’ler genellikle üç temel kimlik doğrulama yöntemi sunar:

• API Anahtarı: Basit ve hızlıdır. İsteğe bir anahtar eklenir. Ancak bu anahtarın sızması durumunda yetkisiz erişim riski yüksektir.
• OAuth 2.0: İzin tabanlı yetkilendirme sağlar. Token süreleri kısa olabilir, yenileme mekanizması gerekir. Bankacılık ve sağlık gibi hassas verilerde standarttır.
• JWT (JSON Web Token): İmzalı token’larla çalışır. İsteklerde taşınması kolaydır, ancak iptali zordur.

Hangi yöntemi seçerseniz seçin, anahtarları ve token’ları asla veritabanında düz metin tutmayın. Ortam değişkenlerini (environment variables) veya gizli yönetim servislerini kullanın. Laravel’de config/services.php dosyası bu iş için uygundur.

Zaman Aşımı ve Yeniden Deneme Stratejileri

API istekleri her zaman başarılı olmaz. Ağ yavaşlar, hedef sunucu çöker, ya da istek yanıtı geç gelir. Bu yüzden zaman aşımı (timeout) ve yeniden deneme (retry) politikanızı baştan belirleyin.

Önerilen strateji: kısa bağlantı zaman aşımı, daha uzun toplam istek süresi. Örneğin, bağlantı için 5 saniye, yanıt için 30 saniye. Yeniden denemeleri ise üstel geri çekilme (exponential backoff) ile artırarak yapın. Aşırı agresif yeniden denemeler hedef API’yi zorlayabilir.

$client->request('GET', 'musteriler', [
    'connect_timeout' => 5,
    'timeout' => 30
]);

Hata Yönetimi ve HTTP Durum Kodlarını Okuma

API yanıtının başarılı olup olmadığını yalnızca HTTP durum koduna bakarak anlayabilirsiniz. 2xx başarılı, 4xx istemci hatası, 5xx sunucu hatası demektir. Ancak durum kodu kadar gövdedeki hata mesajı da önemlidir. Çoğu API, hata detaylarını JSON olarak döner:

{
  "error": {
    "code": 400,
    "message": "Email alanı zorunludur."
  }
}

PHP’de bu yanıtı yakalamak için Guzzle’nin RequestException sınıfını kullanabilirsiniz:

use GuzzleHttpExceptionClientException;

try {
    $response = $client->get('musteriler');
} catch (ClientException $e) {
    $status = $e->getCode();
    $body = json_decode($e->getResponse()->getBody(), true);
    // log ve kullanıcıya anlamlı mesaj döndür
}

Hataları loglamak, sisteminizin sağlığını izlemek için kritiktir. Monolog gibi bir kütüphane ile tüm istek ve yanıtları loglayabilirsiniz; ama dikkatli olun, hassas verileri loglamayın.

API İsteklerinde Performans İyileştirme

Otomasyon sistemlerinde yüzlerce API çağrısı yapmanız gerekebilir. Her istek ağ gecikmesi ekler. Bu yüzden performansı artırmak için şu yolları değerlendirin:

• Cevap önbelleğe alma (caching): Aynı veriyi sık sık çekiyorsanız, sonucu Redis veya memcached’te saklayın.
• Toplu istekler (batch requests): Bazı API’ler birden fazla kaynağı tek istekte çekmenize olanak tanır. Örneğin, Shopify’ın GraphQL toplu işlemleri.
• Eşzamanlı istekler (concurrency): Bağımsız istekleri paralel yürütmek için Guzzle’nin pool özelliğini veya ReactPHP gibi asenkron yaklaşımları kullanın. Ancak bu, sunucu kaynaklarınızı dikkatli kullanmayı gerektirir.

Bir örnek: bir kargo entegrasyonunda 500 siparişin durumunu sorgulamanız gerekiyor. Tek tek beklerseniz işlem dakikalar sürer. Pool ile 10’luk gruplar hâlinde gönderirseniz süreyi ciddi ölçüde azaltabilirsiniz.

Otomasyon ve API Tüketiminde Sık Yapılan Hatalar

Gözlemlediğim kadarıyla şu hatalar çok yaygın:

• Sabit kodlanmış (hard-coded) API anahtarları. Bunun yerine ortam değişkenleri.
• Sonsuz döngüye giren yeniden denemeler. Maksimum deneme sayısı ve üstel geri çekilme şart.
• JSON yanıtını düz metin gibi işlemek. json_decode başarısız olabilir; hata yönetimi unutulur.
• API sürümlemesi (versioning) yapmamak. Çoğu API URL’de v1, v2 gibi sürüm taşır; güncellemeleri takip etmezseniz sisteminiz kırılır.
• Test sırasında canlı API’yi kullanmak. Mutlaka sandbox ortamı tercih edin.

Webhook Kullanımı: API’nin Ötesinde

Çoğu otomasyon sistemi API’yi sürekli sorgulamak yerine, bir olay olduğunda bildirim almayı tercih eder. İşte burada webhook’lar devreye girer. Webhook, harici sistemin sizin belirlediğiniz bir URL’ye HTTP isteği göndermesidir. Ödeme alındığında, kargo durumu değiştiğinde anında haberiniz olur.

PHP tarafında webhook uç noktası oluşturmak basittir: bir route tanımlarsınız ve gelen isteği doğrulayıp işlersiniz. Ancak dikkat etmeniz gereken nokta, gönderenin gerçekten ilgili servis olup olmadığını doğrulamaktır. Örneğin, imza (signature) kontrolü yapın. Ayrıca webhook yanıtlarını hızlı döndürün; yavaş yanıt, hizmet sağlayıcının zaman aşımına neden olup tekrar denemesine yol açar.

İşte basit bir webhook örneği (Laravel route):

Route::post('/webhook/pos', function (Request $request) {
    $payload = $request->getContent();
    $signature = $request->header('X-Signature');
    if (!$this->isValidSignature($payload, $signature)) {
        abort(401);
    }
    // işle, veritabanına kaydet
    return response()->json(['status' => 'ok']);
});

Güvenlik İpuçları: SSL, Rate Limit ve Veri Doğrulama

API entegrasyonlarında güvenlik çok katmanlıdır. İşte dikkat etmeniz gerekenler:

• Her zaman HTTPS kullanın. API’ye giden ve gelen trafiği şifreleyin. Ortam değişkenlerinde bile anahtarı açıkça görmeyin.
• Rate limit kurallarını gözlemleyin. Çoğu API, dakikada kaç istek yapabileceğinizi sınırlar. Bu limiti aşarsanız 429 Too Many Requests alırsınız. İsteklerinizi bu limite göre planlayın.
• Veri doğrulama yapın. API’den gelen verilerin her zaman beklendiği formatta olduğunu varsaymayın. Alan adlarını ve tiplerini kontrol edin. Gelen JSON’u doğrulamak için justinrainbow/json-schema gibi bir kütüphane kullanabilirsiniz.
• Çıktı kodlamasına dikkat edin. API’den gelen veriyi HTML içinde gösteriyorsanız XSS’e karşı kaçış karakterlerini kullanın.

Test Etme Stratejileri: Mock API ve Sandbox Kullanımı

Bir otomasyon sistemini geliştirirken canlı API’ye bağlı kalmak hem yavaş hem de risklidir. Bu yüzden testlerinizde mock servisler kullanın. PHPUnit ve Guzzle’nin mock handler’ı ile sahte yanıtlar tanımlayabilirsiniz. Laravel’de ise Http::fake() metodu çok işinize yarar.

Ayrıca birçok API sağlayıcının sunduğu sandbox ortamı, gerçek verilere benzer test verileriyle çalışmanıza olanak tanır. Yayın öncesi mutlaka sandbox üzerinde uçtan uca test yapın. Canlı ortamda yapılan testler, gerçek müşteri verilerinin bozulmasına ve hesap kilitlenmelerine yol açabilir.

Dokümantasyon ve Bakım: API Değişikliklerini Yönetmek

API’ler zamanla değişir; yeni sürümler çıkar, eski alanlar kaldırılır. Bu yüzden entegrasyon kodunuzu bakımı kolay olacak şekilde yazın.

İyi bir pratik, API katmanını bir sınıf veya servis olarak soyutlamaktır. Örneğin, bir KargoAPI sınıfı oluşturun; tüm istekler ve veri dönüşümleri burada toplansın. Bu sayede API değiştiğinde sadece bu sınıfı güncellersiniz, iş mantığınız etkilenmez.

Ayrıca kullandığınız her üçüncü taraf API’sinin dokümantasyonunu düzenli olarak takip edin. Değişiklik bildirimleri için API sağlayıcının duyuru kanallarını (e-posta, blog, değişiklik günlüğü) abone olun.

Sonuç: API Entegrasyonunu Güvenli ve Sürdürülebilir Kılmak

PHP otomasyon sistemlerinde API kullanımı, dikkatli planlama ve doğru araçlarla oldukça keyifli hâle gelir. İster basit bir ödeme entegrasyonu, ister karmaşık bir kargo takip sistemi kurun, temel prensipler aynıdır: doğru kimlik doğrulama, sağlam hata yönetimi, performansı düşünmek ve güvenliği en baştan tasarlamak.

Bu rehberdeki örnekleri ve stratejileri kendi sisteminize uyarlayarak daha az kesinti, daha az bakım ve daha hızlı geliştirme süreçleri elde edebilirsiniz. Şimdi atmanız gereken ilk adım, mevcut kodunuzda sıkı bağlı API çağrılarını tespit edip bunları bir servis katmanına taşımak. Ardından yeniden deneme ve önbellekleme politikalarınızı gözden geçirin. Küçük adımlarla başlamak, uzun vadede büyük fark yaratır.

Unutmayın: API entegrasyonu bir kez yapılıp bırakılan bir iş değildir. Sürekli büyüyen, değişen bir ekosistemin parçasıdır. Kodunuzu ve bilginizi güncel tutun.