API Nedir ve Nasıl Kullanılır — İstek, Yanıt ve Entegrasyon

Bir e-ticaret sitesine kargo takibi eklemek isteyen işletmeler hep aynı cümleyle karşılaşır: “Kargo firmasının API’sini bağlayın.” Teknik ekip yoksa bu cümle tek başına bir şey anlatmaz. Oysa mantık göründüğünden basittir; bir adrese istek gönderirsiniz, karşı taraf veriyle cevap verir. Bu rehberde API nedir sorusunu, bir çağrının adım adım neye benzediğini ve entegrasyonu ayakta tutan güvenlik ile hosting koşullarını anlatıyoruz.

API nedir ve nasıl çalışır?

API nedir sorusunun teknik karşılığı şudur: bir yazılımın dışarıya açtığı, ne isteneceğini ve karşılığında ne döneceğini önceden tanımlayan kurallı arayüz. Açılımı “application programming interface”, yani uygulama programlama arayüzüdür.

Fark şurada belirir. İnsan bir siteye girer, formu doldurur, düğmeye basar. Yazılımın böyle bir gözü yoktur; sayfayı okumak yerine veriyi doğrudan ister. API bu ikinci yolu açar. Kargo firmasının sitesine girip takip numarasını elle yazmak yerine, siteniz aynı bilgiyi saniyeler içinde çeker ve müşteriye kendi sayfanızda gösterir.

Karşı taraf size veritabanını açmaz. Yalnızca belirlediği işlemleri, belirlediği biçimde sunar. Bu sınır aynı zamanda bir sözleşmedir: dokümanda yazmayan bir alan pratikte yok sayılır, bugün dönen ekstra bir veriye yarın güvenemezsiniz.

İstek ve yanıt mantığı

API nedir sorusunun günlük karşılığı bu akışta görülür. Bir çağrı dört parçadan oluşur. Adres, yani hangi uç noktaya gittiğiniz. Metot, yani ne yapmak istediğiniz. Başlıklar, yani kimlik bilgisi ve veri biçimi. Gövde, yani gönderdiğiniz veri. Sorgulama yapıyorsanız gövde çoğu zaman boştur.

Yanıt iki parçadır: bir durum kodu ve bir gövde. Durum kodu işin sonucunu tek sayıyla söyler, gövde ise istediğiniz veriyi taşır. Entegrasyonu yazarken asıl iş, gövdeyi okumaktan çok durum kodlarını doğru yorumlamaktır. Başarılı yanıtı işlemek kolaydır; asıl fark hata durumunda ne yaptığınızda ortaya çıkar.

REST ve JSON — uç nokta ne demek?

REST, API’leri düzenlemenin en yaygın biçimi. Temel fikri şu: her kaynak bir adrestir. Siparişler /api/v1/siparisler adresinde durur, 1024 numaralı sipariş /api/v1/siparisler/1024 adresindedir. Bu adreslerin her birine uç nokta (endpoint) denir.

API nedir diye soran çoğu kişinin gözünde canlanan şey aslında bu adres yapısıdır. Yanıtlar neredeyse her zaman JSON biçimindedir. JSON, anahtar ve değer çiftlerinden oluşan, hem insanın okuyabildiği hem de her dilin kolayca ayrıştırabildiği bir metin biçimi. XML’e göre daha kısa olduğu için REST ile birlikte standart hâline geldi.

Sürüm numarası adreste görünür (/v1/). Servis sağlayıcı yapıyı değiştireceğinde genelde yeni bir sürüm açar, eskisini bir süre daha çalışır tutar. Entegrasyonunuzu yazarken bu sürüm numarasını sabit tutmak, bir sabah yanıt biçiminin değiştiğini fark etmekten iyidir.

HTTP metotları ve durum kodları

Durum kodlarında 2 ile başlayanlar başarıyı anlatır: 200 istek tamam, 201 yeni kayıt oluştu. 4 ile başlayanlar sizin tarafınızdaki hatayı gösterir: 400 gönderdiğiniz veri hatalı, 401 kimlik doğrulanmadı, 403 yetkiniz yok, 404 kayıt bulunamadı, 429 hız sınırını aştınız. 5 ile başlayanlar karşı sunucudaki sorunu işaret eder; 500 ve 503 bu gruptadır. Tüm metotların ve kodların resmî tanımını MDN HTTP dokümanında bulabilirsiniz.

Ayrım pratikte işe yarar. 4 ile başlayan kodu tekrar denemek anlamsızdır, kodunuzu düzeltmeniz gerekir. 5 ile başlayan kodda ise sorun geçici olabilir; birkaç saniye bekleyip yeniden denemek çoğu zaman çözer.

Anahtar, token ve hız sınırı

Neredeyse hiçbir ciddi servis kimliksiz istek kabul etmez. En basit yöntem API anahtarıdır: panelden aldığınız uzun bir dizeyi her isteğin başlığına koyarsınız. Daha yaygın olan ikinci yöntem token tabanlıdır; kullanıcı adı ve parolayla bir kez oturum açar, size süreli bir token verilir, sonraki istekleri o tokenla yaparsınız. Token süresi dolduğunda yenilersiniz.

Hız sınırı (rate limit), bir servisin belirli bir sürede sizden kabul edeceği istek sayısıdır. Dakikada 60, saatte 1000 gibi. Sınırı aştığınızda 429 yanıtı gelir ve yanıt başlıklarında genelde ne zaman tekrar deneyebileceğiniz yazar. Sınıra takılmamanın en pratik yolu, değişmeyen veriyi önbelleğe almak ve toplu işleri tek tek değil, gruplar hâlinde göndermektir.

Türkiye’de en sık kurulan API entegrasyonları

API nedir sorusu Türkiye’de genelde somut bir ihtiyaçla birlikte geliyor. Kargo takibi başı çeker. Sipariş kargoya verildiğinde takip numarası sisteme düşer, site bu numarayla düzenli olarak durum sorgular ve müşteriye kendi panelinde gösterir. İkinci sırada ödeme altyapıları var; sanal POS entegrasyonlarında ödeme isteği API ile başlatılır, sonucu banka geri bildirim adresine gönderir.

Üçüncüsü e-fatura ve e-arşiv entegrasyonu. Fatura bilgisi özel entegratörün uç noktasına gönderilir, dönen numara sipariş kaydına işlenir. Dördüncüsü stok senkronizasyonu: pazaryerinde ve kendi sitenizde aynı ürünü satıyorsanız, bir kanalda düşen stok diğerine API ile bildirilmediğinde olmayan ürünü satma riski doğar. WooCommerce yazımızda anlattığımız kurulumlarda bu senkronizasyon genelde bir eklenti üzerinden yürür.

WordPress REST API’si nerede duruyor?

WordPress kendi API’sini kutudan çıkarır. Sitenizin /wp-json/wp/v2/posts adresine bir GET isteği attığınızda yazılarınızı JSON olarak alırsınız. Yazı oluşturmak, kategori güncellemek, medya yüklemek de aynı yoldan yapılabilir.

Okuma işlemleri çoğu kurulumda kimliksiz çalışır, yazma işlemleri için kimlik doğrulama gerekir. En pratik yöntem, kullanıcı profilinden üretilen uygulama şifreleridir; asıl parolanızı paylaşmadan yetkili istek göndermenizi sağlar. Uç noktaların tamamı WordPress REST API el kitabında listelidir. Bu arayüzü açık bırakmanın küçük bir yan etkisi de var: kötü niyetli taramalar kullanıcı listesini bu adresten çekmeye çalışır, o yüzden yazma uçlarını yalnızca ihtiyaç duyan hesaplara açmak gerekir.

Entegrasyon için hosting ve güvenlik koşulları

Bir entegrasyonun çalışması için sunucunuzun dışarıya istek atabilmesi gerekir. PHP tarafında bu iş cURL ile yapılır; paylaşımlı hosting kullanıyorsanız cURL desteğinin açık olduğunu ve giden bağlantılarda port kısıtı bulunmadığını baştan sormak en doğrusu. Düzenli sorgulama yapacaksanız zamanlanmış görev (cron) desteği de listenizde olmalı.

İkinci koşul şifreli bağlantı. Ciddi hiçbir servis bugün HTTP üzerinden istek kabul etmiyor; hem siz onlara hem onlar size HTTPS ile ulaşır. Geri bildirim adresi (webhook) tanımlayacaksanız sertifikanızın geçerli olması şarttır, aksi halde karşı taraf bağlantıyı keser. Sertifika türleri ve kurulum sonrası adımlar için SSL sertifikası yazımıza göz atın.

Üçüncüsü kaynak. API çağrıları sayfa yüklenirken senkron çalışıyorsa, karşı taraftaki bir yavaşlama doğrudan sizin sayfa açılış sürenize yansır. Yoğun entegrasyon kuran siteler bu yüzden çağrıları kuyruğa alır ve arka planda işler. WordPress üzerinde çalışıyorsanız hosting tercihi yazımızdaki ölçütler burada da geçerlidir.

• Servisin resmî dokümanını okuyun; uç nokta, metot ve zorunlu alanları not alın.
• Test ortamı (sandbox) varsa canlıya geçmeden önce orada deneyin.
• Anahtarı sunucudaki yapılandırma dosyasında tutun, sürüm kontrolüne göndermeyin.
• Hız sınırını öğrenin ve sık değişmeyen yanıtları önbelleğe alın.
• 4xx ve 5xx kodlarını ayrı ayrı işleyin; 5xx’te kısa bekleyip yeniden deneyin.
• Her isteği ve yanıtı kaydedin, ama kayda anahtar ve kart bilgisi yazmayın.
• Hosting tarafında cURL, giden bağlantı ve cron desteğini önceden doğrulayın.
• Sürüm numarasını sabitleyin, sağlayıcının duyuru kanalını takip edin.