API Nedir? Uygulama Geliştiriciler İçin Sade Rehber

API (uygulama programlama arayüzü), bir yazılımın başka bir yazılımdan veri istemesi ya da ona bir şey yaptırması için tanımlanmış bir yoldur. Uygulamanız üzerinde anlaşılmış bir biçimde bir istek gönderir — "yarınki rezervasyonları ver", "bu karttan 20 € çek", "bu metni özetle" — ve diğer sistem yapılandırılmış bir yanıt döndürür. API'ler bir uygulamanın parçalarının birbiriyle konuşma yoludur ve uygulamanızın ödeme, e-posta, harita ve AI gibi dış servisleri kullanma yoludur.

AI ile geliştirirken API'ler neden önemli?

Neredeyse her işe yarar uygulama, API'ler aracılığıyla iletişim kuran parçalardan oluşur:

• Uygulamanızın içinde, tarayıcıdaki ekranlar veri yüklemek ve kaydetmek için kendi backend'inizin API'sini çağırır.
• Uygulamanızın dışında, backend'iniz başka şirketlerin API'lerini çağırır: ödeme almak için Stripe, makbuz göndermek için bir e-posta sağlayıcısı, metin üretmek için bir AI model sağlayıcısı.

AI oluşturucudan "ödeme al" ya da "bir AI özeti ekle" dediğinizde, aslında yaptığı şey bir API'yi çağıran kodu yazmaktır. Temelleri bilmek, AI'nın sizden neye ihtiyaç duyduğunu (genellikle o servisle bir hesap ve bir API anahtarı), neyin ters gidebileceğini ve maliyetin ne olacağını anlamanıza yardımcı olur.

Günlük hayattan bir benzetme

Bir restoranı düşünün. Mutfağa girip kendiniz pişirmezsiniz. Menüyü okursunuz, garsona mutfağın anlayacağı biçimde ne istediğinizi söylersiniz ve garson yemeğinizi getirir — ya da yemeğin tükendiğini söyler.

• Menü API dokümantasyonudur: neyi nasıl isteyebileceğinizin listesi.
• Garson API'dir: isteklerin girdiği ve yanıtların çıktığı tek, anlaşılmış yol.
• Mutfak diğer sistemdir: içeride nasıl çalıştığını bilmeniz gerekmez.
• Siparişiniz istek; tabak ise yanıttır.

Menü aynı kaldığı sürece mutfak fırınlarını ve personelini sizi etkilemeden değiştirebilir. API'nin gerçek değeri budur: iki sistemin, birinin diğerinin nasıl yapıldığını bilmesine gerek kalmadan birlikte çalışmasını sağlar.

Bir web API isteği nasıl çalışır?

Karşılaşacağınız çoğu API, tarayıcınızın da kullandığı HTTP üzerinden çalışan web API'leridir. Her istekte birkaç parça bulunur:

Her yanıtta ise şunlar bulunur:

JSON (JavaScript Object Notation), süslü parantezler içinde isim ve değerlerden oluşan basit bir metin biçimidir. Web API'lerinin veri alışverişi için standart yoludur.

REST: en yaygın tarz

REST, web API'lerini tasarlamak için yaygın olarak kullanılan bir kuraldır. Her tür şeyin kendi URL'si olur ve standart metodlar onun üzerinde ne yaptığınızı belirtir. Bir randevu uygulaması için bir REST API şöyle görünebilir:

PUT de vardır ve geleneksel olarak tüm kaydı değiştirir; PATCH ise yalnızca gönderdiğiniz alanları değiştirir.

En sık göreceğiniz durum kodları:

Uygulamanız bozulduğunda durum kodu çoğu zaman en hızlı ipucudur. Bir ödeme sağlayıcısından gelen 401 genellikle eksik ya da yanlış bir API anahtarı anlamına gelir; 429 ise çok sık çağrı yaptığınızı gösterir.

REST tek tarz değildir — GraphQL ve RPC tarzı API'ler de vardır — ama çoğu servisin ve AI ile inşa edilen backend'lerin kullandığı REST'tir.

Çalışılmış bir örnek: bir rezervasyon onayı

Bir müşteri bir kuaför uygulamasında saç kesimi rezerve ettiğinde, bir iki saniye içinde birkaç API çağrısı gerçekleşebilir:

1. Tarayıcıdaki rezervasyon sayfası, hizmeti, saati ve müşteri bilgilerini içeren bir POST /api/bookings isteğini backend'inize gönderir.
2. Backend'iniz slotun boş olduğunu kontrol eder, rezervasyonu veritabanına kaydeder ve 201 Created döndürür.
3. Backend'iniz bir e-posta sağlayıcısının API'sini gizli anahtarıyla çağırır: "bu onayı lena@example.com adresine gönder."
4. Bir kapora varsa, backend'iniz ödeme sağlayıcısının API'sinden bir checkout oturumu oluşturmasını ister ve müşteriyi oraya yönlendirir.
5. Daha sonra ödeme sağlayıcısı, ödemenin başarılı olduğunu bildirmek için sizin uygulamanızı çağırır. Bu ters çağrı bir webhook'tur.

İlk iki adım frontend ve backend arasındaki kendi API'nizdir. 3–5. adımlar ise üçüncü taraf API'leridir.

Sık kullanılan terimler

Yaygın hatalar ve yanlış anlamalar

• Gizli anahtarları ön yüze koymak. Tarayıcıda çalışan koddaki her şey, siteyi ziyaret eden herkes tarafından görülebilir. Gizli anahtarlar sunucuda, ortam değişkenlerinde ya da gizli bilgilerde kalmalıdır.
• Anahtarları sohbete yapıştırmak. Sohbet geçmişi saklanabilir. Bunun yerine builder'ınızın gizli bilgiler özelliğini kullanın ve açığa çıkan her anahtarı yenileyin.
• API'nin ücretsiz olduğunu varsaymak. Birçok API istek başına ya da kullanım birimi başına ücret alır — AI model API'leri token başına ücretlendirir. Fiyatlandırmayı kontrol edin ve harcama sınırları koyun. Bkz. LLM API'leri nasıl kullanılır.
• Hataları ele almamak. Dış servisler kapanır, zaman aşımına uğrar ve sınırlara takılır. Makul hata mesajları ve yeniden denemeler isteyin.
• Tarayıcıya güvenmek. Kendi API'niz izinleri kendisi kontrol etmelidir. Bir düğmeyi gizlemek, birinin endpoint'i doğrudan çağırmasını engellemez.
• Test sırasında canlı anahtarlar kullanmak. Lansmana hazır olana kadar test modu anahtarlarını kullanın.

AI oluşturucunuzdan ne istemelisiniz

• "Bu uygulama hangi dış API'leri kullanıyor ve her birinin maliyeti ne?"
• "Ödeme API'sini yalnızca sunucudan çağır. Anahtarı bir ortam değişkeninden oku."
• "API'mizdeki her endpoint'i, ne yaptığını ve kimin çağırmasına izin verildiğini listele."
• "Bir rezervasyonu güncellemeden veya silmeden önce, giriş yapmış kullanıcının ona sahip olduğunu sunucuda kontrol et."
• "E-posta API'si başarısız olursa rezervasyonu yine de kaydet ve hatayı logla."
• "Şimdilik sağlayıcının test modunu kullan."

Mythex'te API'ler

Mythex, kendi API'nizi inşa edebilir — bir web uygulamasının parçası olarak ya da frontend'inizin yanında çalışan, Node, Python (FastAPI), C# veya Java ile yazılmış ayrı bir backend olarak — ve dış servisleri çağıran kodu yazabilir. Anahtarlarını sohbete değil proje gizli bilgileri olarak eklersiniz; önizlemede ve yayınlandıktan sonra uygulamanız bunlara erişir. Dokümanlarda herhangi bir API'yi entegre etme ve REST API backend'i inşa etme için tarifler bulunur.

Sorular