Hava durumu uygulamasını açıyorsunuz ve yarının tahmini bir saniyede ekrana geliyor. Bu tahmini telefon hesaplamadı: Uygulama, hava durumu servisinin sunucusuna tek bir şehri soran kısa bir mesaj gönderdi ve karşılığında birkaç satırlık düz veri aldı, sonra bunu simgelere ve sayılara çevirdi. Bir alışveriş sitesinin ödeme sayfası kartınızdan çekim yapması için ödeme şirketine başvurduğunda ya da iş yerinde biri "Onların API'sini kullan, anahtarın bu" dediğinde de aynı şey olur.
Bu yazıda tek bir API çağrısını istekten yanıta kadar, kendi testimizin gerçek çıktısıyla izliyoruz; ardından HTTP metotlarını, durum kodlarını, API türlerini, anahtarları, hız sınırlarını, sürümlemeyi ve anahtarın güvenliğini anlatıyoruz.
API nedir?
API, bir yazılımın başka bir yazılımdan veri ya da bir işlem istemesinin üzerinde anlaşılmış yoludur. Kısaltma "application programming interface" sözlerinden gelir: "arayüz", çünkü iki programın buluştuğu noktadır; "programlama", çünkü onu ekrana tıklayan bir insan değil, kod kullanır.
Gündelik hayattan iyi bir benzetme ATM'dir. ATM size kısa ve sabit bir menü sunar (bakiye sorgulama, para çekme, şifre değiştirme) ve arkasındaki kasayı hiç görmezsiniz. Kartınız ve şifreniz kim olduğunuzu kanıtlar, günlük limit ne kadar çekebileceğinizi sınırlar, bir sorun olduğunda da "yetersiz bakiye" gibi kısa bir mesaj alırsınız. API de böyle çalışır: sabit bir istek listesi, çağıranı tanıtan bir anahtar, kullanım sınırları ve açık hata yanıtları.
İşletim sistemleri ve tarayıcılar da API sunar, ama gündelik kullanımda "API" denince web API'si kastedilir: internet üzerinden, tarayıcınızın sayfa yüklerken kullandığı protokol olan HTTP ile çağrılan bir servis.
API çağrısı nasıl çalışır?
API çağrısı, bir programın bir API'ye gönderdiği tek istek ve karşılığında gelen yanıttır. Her seferinde aynı adımlardan geçer:
- İstemci isteği hazırlar. İstemci (bir uygulama, bir betik ya da bir sunucu) bir metot (ne yapılacağı), bir endpoint (işlemin adresi), başlıklar (anahtar gibi ek bilgiler) ve bazı metotlarda veriyi taşıyan bir gövde seçer.
- İstek sunucuya ulaşır. DNS sunucunun adını IP adresine çevirdikten sonra istek şifreli bir HTTPS bağlantısıyla gider.
- Sunucu çağıranı denetler: Bu anahtar bu endpoint'i kullanabilir mi, sınırını aştı mı?
- Sunucu işi yapar; örneğin bir veritabanını okur ya da bir ödemeyi başlatır.
- Sunucu yanıt verir: işin nasıl gittiğini söyleyen bir durum kodu, başlıklar ve çoğunlukla veriyi taşıyan bir gövde.
- İstemci yanıtı okur. Önce durum koduna bakar, sonra ihtiyacı olan alanları adlarıyla seçer.
Bir API isteği ve yanıtı neye benzer?
İstek bir metot ve bir endpoint, başlıklar ve bazen bir gövdeden oluşur; yanıt ise bir durum kodu, başlıklar ve çoğunlukla bir gövdeden:
| Bölüm | İstekte | Yanıtta |
|---|---|---|
| İlk satır | Metot + endpoint | Durum kodu |
| Başlıklar | Anahtar, veri biçimi | Veri biçimi, sınırlar |
| Gövde | Gönderilen veri (isteğe bağlı) | Sonuç, çoğunlukla JSON |
Bunu web isteği göndermeye yarayan ücretsiz bir komut satırı aracı olan curl ile görebilirsiniz. JSONPlaceholder, hesap ya da anahtar istemeyen herkese açık bir test API'sidir; denemek için güvenli bir yerdir:
curl -i https://jsonplaceholder.typicode.com/todos/1Test bilgisayarımızda bu komut HTTP/1.1 200 OK durum satırını, Content-Type: application/json; charset=utf-8 başlığını ve şu gövdeyi döndürdü:
{
"userId": 1,
"id": 1,
"title": "delectus aut autem",
"completed": false
}-i seçeneği durum satırını ve başlıkları da yazdırır; metot belirtilmezse curl "oku" anlamına gelen GET gönderir. /todos adresine küçük bir JSON gövdesiyle yaptığımız POST isteği 201 Created ve yeni bir "id": 201 ile döndü. Bu test API'si kaydı gerçekte saklamaz, yalnız saklamış gibi yanıt verir; denemeye elverişli olmasının nedeni de budur. Var olmayan bir kaydı, /todos/999999 adresini istediğimizde ise 404 Not Found aldık.
Gövdenin biçimi JSON'dur (JavaScript Object Notation): neredeyse her programlama dilinin okuyabildiği, ad ve değerlerden oluşan düz bir metin. Standardı olan RFC 8259, sistemler arasında UTF-8 kullanılmasını şart koşar ve medya türünü application/json olarak adlandırır; yukarıdaki başlıkta gördüğünüz değer budur. Daha eski API'ler çoğu zaman XML ile yanıt verir.
API'ler hangi HTTP metotlarını kullanır?
Metot, isteğin fiilidir: okumak, oluşturmak, değiştirmek ya da silmek. HTTP mesajlarının anlamını tanımlayan standart RFC 9110, bazı metotları "güvenli" (yalnız okur), bazılarını da "idempotent" sayar; idempotent, aynı isteği iki kez göndermenin bir kez göndermekle aynı etkiyi yaratması demektir.
| Metot | Tipik işi | Güvenli | İdempotent |
|---|---|---|---|
GET | Bir kaydı ya da listeyi okur | Evet | Evet |
POST | Kayıt oluşturur, işlem başlatır | Hayır | Hayır |
PUT | Bir kaydı baştan yazar | Hayır | Evet |
PATCH | Kaydın bir kısmını değiştirir | Hayır | Varsayılan olarak değil |
DELETE | Bir kaydı siler | Hayır | Evet |
Bu ayrım, bağlantı yarıda koptuğunda önem kazanır. Bir GET isteğini tekrarlamak zararsızdır; bir POST isteğini tekrarlamak ise ikinci bir sipariş ya da ikinci bir ödeme oluşturabilir. Bu yüzden birçok API, POST ile birlikte bir idempotency anahtarı kabul eder: sunucuya "bunu zaten yaptıysan bir daha yapma" diyen benzersiz bir değer.
API durum kodları ne anlama gelir?
Durum kodu her yanıtın başındaki üç haneli sayıdır ve ilk hanesi sonucun kimden kaynaklandığını söyler: 2 başarı, 3 istemcinin yönlendirmeyi izlemek gibi bir adım daha atması gerektiği, 4 isteğin hatalı olduğu, 5 de sunucunun başaramadığı anlamına gelir. API'lerde en sık karşılaşılan kodlar:
200 OKve201 Created: İstek başarılı oldu; 201, yeni bir kayıt oluşturulduğunu söyler.400 Bad Request: İstek hatalı biçimlenmiş; çoğu zaman eksik bir alan ya da bozuk JSON.401 Unauthorized: Geçerli bir anahtar ya da token gönderilmedi.403 Forbidden: Sunucu kim olduğunuzu biliyor, ama bu işleme izniniz yok.404 Not Found: Endpoint ya da kayıt yok.429 Too Many Requests: Hız sınırını aştınız.500 Internal Server Error: Sunucu isteği işlerken hata verdi.
İyi tasarlanmış bir API hatayı gövdede de açıklar. Kendi API'mizin /me endpoint'ini token olmadan çağırdığımızda 401 Unauthorized, beklenen yöntemi söyleyen bir www-authenticate: Bearer başlığı ve içinde hata kodu, tek satırlık bir mesaj ("Missing or malformed Authorization header") ile destek ekibine iletilecek bir istek kimliği bulunan JSON gövdesi döndü.
Hangi API türleri vardır?
Web API'leri en çok isteklerin nasıl kurulduğuna göre ayrılır ve karşılaşacağınız API'lerin çoğu dört biçimden birindedir:
| Tür | Nasıl istenir | Tipik kullanım |
|---|---|---|
| REST | Her kaynağın kendi adresi | Herkese açık web API'lerinin çoğu |
| GraphQL | Tek endpoint, alanları siz seçersiniz | Esnek veri isteyen uygulamalar |
| gRPC | Şema dosyasında tanımlı çağrılar | Şirket içi servisler arası |
| Webhook | Servis sizi çağırır | Olay bildirimleri |
REST (representational state transfer), her nesneye /orders/42 gibi kendi adresini verir ve yukarıdaki HTTP metotlarıyla o adres üzerinde işlem yapar. Biri ayrıntı vermeden "API" dediğinde çoğunlukla REST tarzı, JSON döndüren bir API kastedilir. GraphQL'de bütün istekler tek bir endpoint'e gider ve istemcinin sorgusu geri istediği alanları tek tek listeler. gRPC her çağrıyı önceden bir şema dosyasında tanımlar ve veriyi varsayılan olarak Protocol Buffers adlı sıkıştırılmış ikili bir biçimde gönderir.
Webhook yönü tersine çevirir: Programınızın her dakika "yeni bir şey var mı?" diye sorması yerine servise kendi adresinizi verirsiniz, servis de "ödeme alındı" gibi bir olay olduğunda o adrese bir istek gönderir.
API'ler kimin kullanabileceğine göre de ayrılır. Herkese açık (public) bir API'ye kaydolan her geliştirici erişebilir; iş ortağı (partner) API'si, bir pazar yerinin satıcı entegrasyonu gibi yalnız sözleşmeli şirketlere açılır; özel (private) API ise yalnız şirketin kendi uygulama ve servislerini birbirine bağlar.
API anahtarı nedir, token'dan farkı ne?
API anahtarı, API'yi çağıran programı tanıtan uzun ve gizli bir karakter dizisidir; ATM'deki kartın karşılığıdır. Sunucu her istekte bu anahtara bakarak çağıranın kim olduğuna, neler yapabileceğine ve hangi sınırların geçerli olduğuna karar verir. Anahtar çoğunlukla siz iptal edene kadar geçerli kalır.
Token aynı işi görür, ama genellikle daha kısa bir süre ya da daha dar bir amaç için verilir. "Hesabınızı bağlayın" ekranlarının çoğunun arkasındaki standart OAuth 2.0'dır: Bir uygulamaya servisin kendi sayfasında izin verirsiniz, uygulama da şifrenizi hiç görmeden yalnız onayladığınız izinlerle (scope) sınırlı bir erişim belirteci (access token) alır. Bu token'ların çoğu RFC 6750 ile tanımlanan bearer token'lardır: Elinde bulunduran herkes kullanabilir; bu yüzden Authorization başlığında taşınır, asla bir sayfa adresinde (URL) taşınmaz.
| Yöntem | Neyi kanıtlar | Tipik kullanım |
|---|---|---|
| API anahtarı | Hangi program ya da hesap çağırıyor | Sunucudan sunucuya çağrılar |
| OAuth token'ı | Kullanıcı uygulamaya neye izin verdi | Bağlı hesaplar |
| IP izin listesi | Çağrı nereden geliyor | Bankalar, borsalar, B2B |
API anahtarını servisin sitesindeki hesabınızın geliştirici ya da API bölümünden alırsınız: Anahtarı oluşturun, yalnız ihtiyaç duyduğu izinleri işaretleyin ve kopyalayın; birçok servis anahtarın tamamını yalnız bir kez gösterir. Bu sitenin Docs bölümünde anlatılan kendi API'miz de bearer token'ı yalnız Authorization başlığında kabul eder, URL'de ya da çerezde asla kabul etmez. Her token kendi izinlerini taşır; yalnız okuma izni olan bir token sipariş veremez.
Hız sınırı (rate limit) nedir?
Hız sınırı, bir çağıranın belirli bir sürede yapabileceği çağrı sayısıdır; örneğin anahtar başına dakikada 60 istek. Servisi aşırı yükten korur ve tek bir yoğun kullanıcının herkesi yavaşlatmasını önler. Sınır aşıldığında API, süre penceresi sıfırlanana kadar 429 Too Many Requests ile yanıt verir.
Birçok API kalan hakkınızı yanıt başlıklarında bildirir. Bizim API'miz her yanıtta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını gönderir; bu adlar yaygın bir adlandırma geleneğidir, sabit bir standart değildir, bu yüzden her API'nin dokümantasyonuna bakın. Hata geldiğinde ne yapılacağını 429 Too Many Requests ve Rate Limit Hatası Nedir? yazımızda anlattık.
API'ler nasıl sürümlenir ve belgelenir?
API'ler, sunucudaki bir değişiklik onu zaten çağıran programları bozmasın diye sürümlenir. En görünür yol, kendi temel adresimiz https://api.proxynet.io/api/v1 örneğindeki gibi sürüm numarasını yola yazmaktır: Uyumsuz değişiklikler v2'ye gider, v1 de çoğunlukla duyurulan bir süre boyunca çalışmayı sürdürür. Bazı API'ler sürümü bunun yerine bir başlıkta taşır.
Dokümantasyon API'nin sözleşmesidir: Her endpoint metoduyla, parametreleriyle, örnek bir yanıtla ve döndürebileceği hatalarla birlikte listelenir. Birçok API dokümantasyonunu OpenAPI Specification biçiminde yayımlar; bu, bir HTTP API'sini hem insanların hem araçların okuyabileceği şekilde anlatan bir JSON ya da YAML dosyasıdır (3.2.1 sürümü 10 Eylül 2026'da yayımlandı). Araçlar bu dosyadan bir başvuru sayfası oluşturabilir, istemci kodu üretebilir ya da bir "dene" paneli kurabilir.
API anahtarı nasıl güvende tutulur?
API anahtarına şifre gibi davranın: Anahtarı ele geçiren sizin adınıza işlem yapabilir, ücretli bir API'de de sizin paranızı harcayabilir. Sızıntıların çoğu basit nedenlerden çıkar:
- Koda yazılmış anahtar. Bir betiğe yapıştırılan anahtar Git deposuna gider; anahtarı bir ortam değişkeninde ya da bir gizli bilgi yöneticisinde (secrets manager) tutun.
- Ön yüz kodundaki anahtar. Tarayıcıya ya da mobil uygulamaya giden her şeyi kullanıcılar okuyabilir; API'yi kendi sunucunuzdan çağırın.
- URL'deki anahtar. Adresler sunucu kayıtlarına ve tarayıcı geçmişine yazılır.
- Her işe tek anahtar. Her entegrasyona en az izinle kendi anahtarını verin; böylece sızan anahtarı tek başına iptal edebilirsiniz.
- Hiç değişmeyen anahtar. Anahtarı düzenli aralıklarla ve bir sızıntıdan hemen sonra yenileyin: Yenisini oluşturun, programı ona geçirin, eskisini silin.
Sağlayıcı tarafında OWASP Vakfı'nın API Security Top 10 listesi en sık görülen API açıklarını sıralar. 2023 listesinin ilk sırasında nesne düzeyinde yetkilendirme hatası (broken object level authorization) var: 42 numaralı kaydı, çağıranın o kaydın sahibi olup olmadığına bakmadan isteyen herkese döndüren bir endpoint.
API ile web scraping arasındaki fark nedir?
API, sağlayıcının paylaşmayı seçtiği veriyi belgelenmiş bir biçimde ve yazılı sınırlar içinde verir; web scraping (veri kazıma) ise insanlar için hazırlanmış sayfaları indirip veriyi HTML'in içinden ayıklar. İhtiyacınız olan alanları taşıyorsa API daha sağlam yoldur; scraping ise hiçbir API'nin sunmadığı veriye ulaşır, ama sayfa düzeni değiştiğinde bozulur. İkisini, aynı veriyi iki yoldan da çekerek Web Scraping ve API Farkı yazımızda karşılaştırdık.
Bazı API'ler neden yalnız belirli IP adreslerinden gelen çağrıları kabul eder?
Bazı API'ler çağrının hangi anahtarı taşıdığına ek olarak nereden geldiğine de bakar. Bankalar, kripto borsaları, pazar yerleri ve birçok kurumsal veri servisi bir anahtar için IP adresi kaydetmenize izin verir; bu bir IP izin listesidir (IP whitelist). Başka yerden gelen çağrılar doğru anahtarla bile reddedilir; böylece çalınan bir anahtar başkasının bilgisayarında işe yaramaz.
Bu durumda programınızın sabit bir çıkış adresine ihtiyacı olur; ev bağlantılarında, dizüstü bilgisayarlarda ve birçok bulut fonksiyonunda böyle bir adres yoktur. Seçenekleri API için Statik IP yazımızda karşılaştırdık.
Ödeme ya da sağlık verisi taşımayan test kurulumları ve entegrasyonlar için ISP Proxy, betiğiniz için, API'ye kaydedebileceğiniz ve yalnız size ayrılmış tek bir IP verir.
Datacenter Proxy aynı işi bir veri merkezi adresiyle görür. İkisi de varsayılan olarak hedef site kısıtlamasıyla gelir; bu yüzden sipariş verirken API'nin alan adını belirtirsiniz. Ödeme ve sağlık entegrasyonlarında ise kendi sunucunuzun adresini kaydedin.
API'lerle nerede karşılaşırsınız?
- Telefon uygulamaları, hava durumunu, mesajları ve haritaları sunucularından çekerken.
- Çevrim içi ödeme sayfaları, mağaza kartınızdan çekim için ödeme şirketinin API'sini çağırırken.
- "… ile giriş yap" düğmeleri, sınırlı bir profil bilgisini başka bir siteyle paylaşırken.
- Bütçe uygulamaları, banka buna bir API sunuyorsa birkaç bankadaki bakiyeyi tek ekranda gösterirken.
- Kargo takibi, mağazanın sayfası bilgiyi kargo firmasının API'sinden alırken.
- Başka ürünlerin içindeki yapay zekâ özellikleri, prompt'unuzu bir dil modeline onun API'si üzerinden gönderirken.
Sık yapılan hatalar
- Durum kodunu atlamak.
401ya da429yanıtının gövdesini veri sanmak boş ya da yanlış sonuç verir. POSTisteğini körlemesine tekrarlamak. İkinci bir sipariş ya da ödeme oluşabilir; API sunuyorsa idempotency anahtarı kullanın.- Anahtarı koda gömmek. Anahtar depolara, ekran görüntülerine ve sohbet mesajlarına yayılır.
- 429 aldıktan sonra üstelemek. Hemen yapılan yeni denemeler sizi sınırın üstünde tutar; sıfırlanma zamanını bekleyin.
- Yanlış dokümantasyonu okumak. Alanlar ve sınırlar sürümden sürüme değişir; çağırdığınız sürümün dokümantasyonunu okuyun.
Karar rehberi
| İhtiyacınız | Ne yapmalı |
|---|---|
| İlk kez bir API denemek | Herkese açık bir test API'sine curl -i |
| Kullanıcının hesabını bağlamak | En az izinle OAuth |
| Olaylardan anında haberdar olmak | Sürekli sormak yerine webhook |
| Sınırların içinde kalmak | Hız sınırı başlıklarını okuyun |
| IP izin listesi isteyen bir API | Tek bir sabit IP kaydedin |
| Anahtarı saklamak | Ortam değişkeni ya da gizli bilgi yöneticisi |
Sıkça sorulan sorular
API'nin açılımı nedir?
API, "application programming interface" yani uygulama programlama arayüzü demektir: Bir programın başkalarına sunduğu istekler ile her isteğin neyi içermesi gerektiğine ve ne döndüreceğine dair kurallar. Web'de bu söz çoğunlukla JSON ile yanıt veren bir HTTP API'sini anlatır.
API çağrısı ne demek?
API çağrısı, bir programın bir API'ye gönderdiği tek istek ve onun yanıtıdır. Örneğin GET /todos/1 tek bir kaydı ister; sunucu 200 OK gibi bir durum kodu ve JSON biçiminde kayıtla yanıt verir. Ücretli API'ler çoğu zaman çağrı başına ücret alır.
API endpoint'i nedir?
Endpoint, bir API'nin sunduğu tek bir işlemin adresidir ve API'nin temel adresi ile bir yoldan oluşur; örneğin https://api.example.com/v1/orders. Aynı yol metoda göre farklı iş görebilir: GET siparişleri listeler, POST yeni bir sipariş oluşturur.
API kullanmak ücretsiz mi?
Sağlayıcıya göre değişir. Bazı API'ler anahtar bile istemez, birçoğu belirli bir kotaya kadar ücretsizdir ve sonrasında çağrı başına ücret alır, bazıları ise yalnız müşterilere ya da iş ortaklarına açıktır. Fiyat, sınırlar ve veriyle neler yapabileceğiniz sağlayıcının kendi sayfalarında yazar.
API gateway nedir?
API gateway (API ağ geçidi), bir ya da daha fazla API'nin önünde duran ve ortak işleri önce üstlenen bir sunucudur: Anahtarları denetler, hız sınırlarını uygular, her yolu doğru servise yönlendirir ve trafiği kaydeder. Çağıran tek bir adres görür; arkasında ise birçok servis olabilir.
API kullanmak için kod bilmek gerekir mi?
Denemek için gerekmez. Herkese açık bir API'yi curl ile ya da birçok dokümantasyon sitesindeki "dene" paneliyle çağırabilirsiniz; kodsuz otomasyon araçları da API'leri formlar üzerinden birbirine bağlar. Bir API'yi kendi ürününüze eklemek ise kod ister, ama basit bir entegrasyon çoğu zaman birkaç düzine satırdır.
Özet
API, bir programın başka bir programa gönderebileceği sabit isteklerdir: Bir metot ve bir endpoint, bir anahtar ya da token ile gider; bir durum kodu ve çoğunlukla JSON biçiminde veri geri gelir. En yaygın biçim REST'tir; GraphQL esnek sorgular, gRPC şirket içi servisler, webhook ise olay bildirimleri için kullanılır. Anahtarları koddan ve URL'lerden uzak tutun, veriden önce durum kodunu okuyun; bir API yalnız kayıtlı adreslerden gelen çağrıları kabul ediyorsa ona güvenebileceği tek bir sabit IP verin.




