API nedir
API, iki programın üzerinden konuştuğu sözleşmedir: biri üzerinde anlaşılmış bir biçimde istek gönderir, öteki üzerinde anlaşılmış bir biçimde yanıt döndürür ve hiçbirinin ötekinin içeride nasıl çalıştığını bilmesi gerekmez. Web'de düğmesine bastığınız ve başka bir yerden veri getiren hemen her şeyin arkasında bir API vardır.
- Ders 11 / 14
- Başlangıç
- Ücretsiz, kayıt yok
İki program arasındaki sözleşme, tahta tahta
Sizin programınız
Karşı tarafın içeride nasıl çalıştığını bilmesi gerekmez
Karşıdaki hizmet
Yalnızca sözleşmenin söylediğini ve kotanın izin verdiği kadarını verir
Köprüyü karşı taraf kurdu ve onu değiştirebilecek olan da o. API adresinde bir sürüm numarasının bulunmasının nedeni budur: sürüm bir yaşadığı sürece yanıtın biçimi olduğu gibi kalır.
Son kontrol: Bu dersteki bilgiler ve araç adları bu tarihte kaynaklarıyla yeniden doğrulanır.
Bu sitenin size gösterebileceği bir örnek
Bu sitenin ücretsiz site hızı kontrolünü açın ve bir adres verin. O düğmenin arkasında olan şey tam olarak API tanımıdır ve üç tarafı vardır.
Tarayıcınız adresi sunucumuza gönderir, sunucumuz aynı adresi Google'ın PageSpeed hizmetine verir, Google sayı dolu, JSON biçiminde yapılandırılmış bir metin döndürür ve sunucumuz o sayılardan birkaçını alıp sayfaya verir. Bu zincirin hiçbir yerinde insan yoktur ve üç programın hiçbiri diğerinin içeride nasıl yazıldığını bilmez.
API işte bu sözleşmedir: her biri belirli bir girdi alıp belirli bir çıktı veren adresler kümesi. Adı uygulama programlama arayüzü anlamına gelir ve önemli kısmı arayüz kelimesidir. Priz gibi: prizin biçimi sözleşmedir ve elektriğin nereden geldiğini bilmeniz gerekmez.
Ve öğrenmenin en kısa yolu şu nokta: bugünkü web API'lerinin çoğu egzotik bir şey değil, HTML sayfası yerine JSON metni döndüren bir internet adresidir. Tarayıcıda bir bağlantı açabiliyorsanız ilk API çağrınızı da yapabilirsiniz.
Her çağrının dört parçası vardır
Birinci parça adrestir; her birine uç nokta denir ve tanımlı tek bir iş yapar. İkincisi yöntemdir: GET bir şey istiyorum, POST kaydedilmek üzere bir şey gönderiyorum demektir. Üçüncüsü girdiler olan parametreler, dördüncüsü yanıttır.
Yanıtın kendisinin iki parçası vardır ve yeni başlayanlar genelde yalnızca birini görür. İlki durum kodudur: 200 oldu, 400 isteğinizde kusur var, 404 böyle bir şey yok, 429 fazla hızlı istediniz ve 500 onların tarafında bir şey bozuldu demektir. İkinci parça ise gövdedir, genelde JSON.
Zamanınızı kurtaran şey o durum kodunu okumaktır. Başındaki 4, kusurun çağıran tarafta olduğunu ve isteğin düzeltilmesi gerektiğini; başındaki 5 ise kusurun hizmet tarafında olduğunu ve isteğinizi düzeltmenin bir şey kazandırmayacağını söyler. Bu ayrımı bilmeyen biri, karşı hizmet bozukken saatlerce kendi kodunu arar.
Bu sitenin kendi API'si de aynı biçimde. rgb/v1 ad alanı altında altı uç nokta var: ilk dördü alan adı, SEO, hız ve güvenlik kontrolleri için GET, diğer ikisi iletişim formu ve görüntülenme sayacı için POST kullanıyor. Her yanıtın sabit bir zarfı var: başarılı olup olmadığını söyleyen bir anahtar, ardından ya veri ya hata mesajı. Bir API'yi tüketen için bu tekdüzelik her belgeden önemlidir.
Anahtarlar ve hız sınırları: neden sonsuz ücretsiz API yoktur
Her API çağrısı karşı tarafa bir şeye mal olur; bu yüzden onu denetlemek için iki araç vardır. Birincisi anahtar: sizi tanımlayan ve bu isteklerin kime ait olduğunu belli eden bir dizge. İkincisi hız sınırı: belirli bir zaman aralığındaki istek sayısına konan bir tavan; onu aştığınızda yanıt 429 olur.
Bu sitede yaşanan gerçek bir olay ikisinin de neden önemli olduğunu gösteriyor. Hız aracımız bir süre Google'ın API'siyle hiç anahtarsız çalıştı ve doğru yanıt verdi. Sonra bizim tarafımızda hiçbir değişiklik olmadan aynı istekler 429 dönmeye başladı ve hata metninde günlük kota sıfırdı. Çözüm tek satırdı: bir anahtar alıp sitenin yapılandırmasına koymak. Geriye kalan ders: bir API'nin bugünkü davranışı yarının sözleşmesi değildir, hele anahtarsız bir hizmet kullanıyorsanız.
Öteki taraf da öğreticidir: kendi API'mizin de sınırları var, çünkü herkese açık ve hiç anahtar istemiyor. Tavanlar ziyaretçi başına ve beş dakikalık pencerede: 20 alan adı kontrolü, 10 SEO kontrolü, 10 güvenlik kontrolü ve 6 hız kontrolü; çünkü her hız kontrolü kendisi dış bir hizmete yapılan pahalı bir çağrıdır. İletişim formunun kendi bütçesi var: saatte 5 gönderim.
Bir gün kendiniz herkese açık bir API yazarsanız, bunu öğüt olarak değil deneyim olarak alın: hız sınırını ilk gün koyun, gereksiz görünse bile. Bir betik hizmetinizi dövmeye başladıktan sonra eklemek her zaman geçtir.
Girdiyi ziyaretçi yazdığında: herkesin unuttuğu koruma
Bu sitedeki araçların, onları sıradan bir API'den ayıran ortak bir özelliği var: kontrol edilen adresi ziyaretçi yazıyor ve sonra sunucumuz o adrese bir istek yapıyor. Yani bir yabancı, sunucumuza nereye bağlanacağını söyleyebiliyor.
Bu dizginlenmezse biri kendi sitesi yerine bir iç ağ adresi yazabilir. Bir ağın içinde duran ve bir yabancının tarayıcısının erişemediği yerlere erişebilen sunucumuz da o adresi açar ve sonucu ona gösterir. Bu güvenlik açığı sınıfına SSRF denir ve çaresi iyi bilinir.
Bu sitenin kodunda yazdığımız koruma dört şey yapar ve sırası önemlidir. Yalnızca http ve https kabul eder; yalnızca 80 ve 443 numaralı portları kabul eder; içinde kullanıcı adı ve parola taşıyan bir adresi reddeder; ve en önemlisi, alan adını IP adreslerine çözer ve dönen her adresi denetler, biri bile özel ya da ayrılmışsa isteğin tamamını reddeder.
Genelde unutulan madde sonuncusudur. Doğrudan özel IP taşıyan adresleri engellemek kolaydır ve bunu herkes yapar; ama bu korumayı aşmak isteyen kişi, iç bir IP'ye işaret eden, sıradan görünen bir alan adı kaydeder. Bunu durdurmanın tek yolu çözümleme adımı ve sonucunun denetlenmesidir, adresin biçimine bakmak değil.
Sunucu ziyaretçinin adresine bağlanmadan önceki dört denetim
-
Yalnızca http ve https
Diğer her şema reddedilir, çünkü bu iş için yalnızca bu ikisi gereklidir.
-
Yalnızca 80 ve 443 portları
Standart dışı bir port genelde birinin aynı makinedeki başka bir hizmetin peşinde olduğu anlamına gelir.
-
Adreste kullanıcı adı ve parola yok
İçinde kimlik bilgisi taşıyan bir adres ya bir hatadır ya bir tuzak.
-
Adı çöz ve dönen her adresi denetle
En önemli ve unutulan adım: sıradan bir alan adı iç bir IP'ye işaret edebilir.
Bu sıra, ziyaretçiden adres alan bir API içindir. Sizinki böyle bir girdi almıyorsa bu korumaya gerek yoktur; onun yerine başka şeyler gerekir.
Sahibi olmadığınız bir API bir gün yanıt vermez
Programınız başka bir hizmete bağlandığında, denetlemediğiniz bir bağımlılık yaratmış olursunuz. Hizmet yavaşlayabilir, kapanabilir, yanıtının biçimini değiştirebilir ya da ücretsiz kotasını geri çekebilir. Bunların hiçbiri nadir değildir ve yalnızca başarı durumu için yazılmış bir program o gün çöker.
Üç basit savunma neredeyse her zaman yeter. Birincisi zaman aşımı: her dış çağrının bekleme tavanı olmalı, yoksa onların yavaşlığı sizin yavaşlığınız olur. İkincisi önbellek: yanıtı kısa bir süre saklayın ki tekrarlanan bir girdi yeni bir çağrı doğurmasın. Üçüncüsü ikinci bir plan: yanıt gelmediğinde program ne diyeceğini bilmeli.
Bu sitenin hız aracında üçü de var ve canlı bir örnek: her adresin sonucunu on dakika saklıyor, yani aynı adres yeniden kontrol edilirse Google'a hiçbir çağrı yapılmıyor; o hizmetten yanıt gelmezse de hata göstermek yerine daha basit bir yerel denetim çalışıyor ve ziyaretçi eli boş kalmıyor.
Ve genelde bir iki kez yandıktan sonra öğrenilen bir nokta: sürümleme. Kendi API ad alanımızdaki o v1, yanıt biçimi bir gün değişirse bir sürüm iki oluşturulacağı ve sürüm bire bağlı olanın kırılmayacağı anlamına gelir. Herkese açık bir API için bu, tüketiciye saygıdır ve maliyeti adreste üç fazladan karakterdir.
Yapay zekayla hızlı yol
Yapay zekanın burada gerçekten kısalttığı şey, tanımadığınız bir API'nin belgelerini okuyup ilk doğru çağrıya ulaşmaktır; eskiden yarım gün süren iş. Ama işe yarayan sürüm, "bana kodu yaz" isteğinden tek bir noktada ayrılır: kod yerine, önce kendinizin çalıştırıp bakabileceği tek bir deneme çağrısı istersiniz. Gerçek bir yanıtı gördükten sonra kod yazmak on dakikalık iştir; öncesinde yazmak tahmindir.
- O API'nin belge sayfasını alın ve yalnızca bağlantısını değil, sayfanın metnini gönderin. Model sayfayı göremezse belleğinden yanıt verir ve API belgeleri hızla değişir.
- Aşağıdaki reçeteyle anahtarsız ya da bir test anahtarıyla çalıştırılabilecek tek bir deneme çağrısı isteyin ve onu kendiniz çalıştırın. İlk gördüğünüz şey durum kodudur ve nerede olduğunuzu o söyler.
- Gerçek yanıtı aldığınızda onu geri verin ve yalnızca şu üç alana ihtiyacınız olduğunu söyleyin. Artık model verinin gerçek biçimini görür ve yazdığı kod gerçekte dönenle örtüşür.
- Son olarak hata durumlarını eklemesini isteyin: zaman aşımı, 429 ve hiç JSON olmayan bir yanıt. Bu üçü, ilk gün asla olmayan ve ikinci ayda mutlaka olan durumlardır.
Kopyalamaya hazır şablon
Bu API'nin belgelerinin metni şu:
{belge sayfasının metni}
Yapmak istediğim: {örneğin, bir siparişin durumunu numarasıyla almak}
Şu sırayla yanıtla:
1. Şu anda terminalde çalıştırabileceğim tek bir deneme çağrısı ver; doğru yöntem, adres ve parametrelerle. Anahtar gerekiyorsa nereden alındığını ve isteğin hangi kısmına konduğunu söyle.
2. Başarılı bir yanıtta hangi alanlara bakacağımı söyle.
3. Bu uç noktanın döndürdüğü durum kodlarını ve her birinin ne demek olduğunu listele.
4. Hız sınırının ya da kotasının ne olduğunu söyle. Belgelerde yazmıyorsa yazmadığını yaz ve tahmin etme.
Henüz uygulama kodu yazma; yalnızca deneme çağrısı.Çıktıya güvenmeden önce: Bir modelin verdiği herhangi bir çağrıyı çalıştırmadan önce iki şeyi kendiniz denetleyin. Birincisi, o çağrının ne yaptığı: bir <code>GET</code> genelde yalnızca okur, ama bir <code>POST</code> ya da <code>DELETE</code> gerçek hesabınızda bir şeyi değiştirebilir ve geri almak sizin elinizde olmaz. İkincisi, API anahtarı bir sırdır: bir sohbete yazdığınız komuta asla gerçek bir anahtar koymayın; bir kez koyduysanız o anahtarı iptal edip yenisini oluşturun. Ve her seferinde çıkan bir şey: belgeler istek tavanı hakkında bir şey söylemiyorsa model genelde makul bir sayı uydurur. O sayı hiçbir yerden gelmiyor.
Bu işte yapay zeka
Bu konuda bir dil modeli iki şeyi iyi yapar ve bir şeyi hiç yapmamalıdır. İyi yaptığı: uzun belgeleri okuyup ihtiyacınız olan birkaç satırı çıkarmak ve bir JSON yanıtını kullanılabilir hale getiren kodu yazmak. Hiç yapmaması gereken: belgeleri bellekten üretmek. Belge sayfasını vermezseniz alan ve parametre adlarını tam bir güvenle uydurur ve siz asla çalışamayacak bir kodu ayıklamakla bir saat geçirirsiniz.
Gerçekten işe yarayan araçlar
- Claude Bu sayfadaki reçeteye uygundur; çünkü uzun belge metni bütün olarak yapıştırılabilir ve gerçek API yanıtı da aynı konuşmada verilebilir. İran, Anthropic'in iki desteklenen ülke listesinin hiçbirinde yok; bunu Anthropic'in kendi sayfasında okuduk.
- Claude Code Tek bir çağrı değil, bütün bir tümleştirme yazarken daha yararlıdır; çünkü projenin kodunu görür ve deneme çağrısını kendisi çalıştırabilir. Ücretsiz kurulur ama bir Claude aboneliği ya da Anthropic Console hesabı olmadan çalışmaz.
- Gemini Bir JSON yanıtını koda çevirmek ve tekrarlayan mekanik işler için hızlı ve ucuz bir model yeter. Google'ın kendi sayfası Gemini web uygulamasının 230'dan fazla ülke ve bölgede çalıştığını söylüyor ve İran o listede yok.
Nerede geri teper
Bu konudaki somut risk, var olmayan bir uç nokta ya da parametredir. Model yaygın API'lerin biçimini iyi bilir; bu yüzden belgeleri görmediğinde gerçek bir API'ye benzeyen bir şey üretir: alan adları makuldür, yapı doğru görünür ve hiçbiri sizin hizmetinizde yoktur. Anthropic bu dayanaksız güven sınıfını kendi belgelerinde halüsinasyon diye adlandırıp azaltma yollarını anlatıyor; bu iş için en basit azaltma, belge metnini vermektir.
İkinci risk anahtara aittir. API anahtarı programınızın parolasıdır ve onu elinde tutan, sizin hesabınıza istek yapabilir ve kotanızı harcayabilir. Bu yüzden gerçek bir anahtar ne bir sohbete ne de bir depodaki koda girer; yeri deponun dışındaki bir ayar dosyasıdır, tıpkı git dersinde söylediğimiz gibi. Her aracın İran'dan nasıl ödenebileceği için satın alma rehberine bakın.
Kaynaklar: MDN: an overview of HTTP MDN: HTTP response status codes Anthropic: reduce hallucinations Anthropic: supported countries Google: where the Gemini web app is available
Bu tavsiyenin sınırı
Bu ders web API'leriyle ilgilidir; HTTP üzerinden çalışan ve JSON döndürenlerle, çünkü bugün karşılaştığınızın çoğu budur. Birkaç şey bilerek dışarıda bırakıldı: programınız başka bir hizmette bir kullanıcının hesabına bağlandığında gereken OAuth gibi daha ağır kimlik doğrulama; yönün tersine döndüğü ve karşı hizmetin sizi çağırdığı web kancaları; ve farklı bir sözleşmesi olan GraphQL gibi biçemler. Burada da geçerli bir sınır: 200 durum kodu yalnızca çağrının geçtiğini ve bir yanıt geldiğini söyler. O yanıtın içeriğinin doğru olması ayrı bir garantidir ve onu hiçbir API vermez.
Kendi işimizden
Bu derste bu sitenin kendi API'si hakkında söylenen her şey, sitenin temasındaki tek bir dosyadan okundu ve orada görülebilir: rgb/v1 ad alanı altında altı uç nokta, dördü GET ikisi POST, hiçbiri anahtar istemiyor ve hepsi ziyaretçi başına hız sınırlı. O kodda eğitimlerde nadiren görülen iki şey var. Birincisi, yalnızca adresin biçimine bakmayan SSRF koruması: alan adını IP adreslerine çözer ve dönen adreslerden herhangi biri özel ya da ayrılmışsa isteğin tamamını reddeder. İkincisi, dış hizmet yanıt vermediğinde hız aracının yaptığı şey: hata göstermek yerine daha basit bir yerel denetim çalıştırır ve her adresin sonucu on dakika saklanır, böylece tekrar çağrı yapılmaz. Anahtar hikâyesi de gerçek: aynı çağrı bir süre anahtarsız çalıştı, sonra günlük kotası sıfır olarak 429 dönmeye başladı ve sitenin yapılandırmasına bir anahtar eklenerek düzeldi.
Gerçek devam soruları
API ile web servisi arasındaki fark nedir?
Web servisi, ağ üzerinden erişilebilen bir API'dir. Her API bir ağdan geçmez; kendi programınızın içinde çağırdığınız bir kütüphanenin de bir API'si vardır. Gündelik konuşmadaysa iki kelime genelde aynı anlamda kullanılır.
İlk API çağrım için nereden başlamalıyım?
Anahtar istemeyen ve GET ile çalışan herkese açık bir API'den; adresini tarayıcıda açın ve JSON'a bakın. Yanıtın biçimi tanıdık geldiğinde aynı çağrıyı curl gibi bir araçla, sonra kodun içinden yapın. Bu sıra birkaç saatlik kafa karışıklığını ortadan kaldırır.
429 aldım, bu ne demek?
İstek tavanını aştığınızı ve beklemeniz gerektiğini söyler; kodunuzun kusurlu olduğunu değil. Önce hizmetin yanıtında ne kadar bekleneceğini söyleyip söylemediğine bakın; sonra çağrılar tekrarlıysa yanıtı önbelleğe alarak sayılarını azaltın.