Otomasyon yazan bir sistem yöneticisi er ya da geç bir API ile karşılaşır: bulut sağlayıcısından sunucu listesi çekmek, izleme sistemine olay bildirmek, kimlik sağlayıcıdan kullanıcı sorgulamak. Kavramların birkaçını bilmek, belgelerin geri kalanını okunabilir kılar.
API ne demek
API, bir sistemin başka programlara sunduğu arayüzdür. Kullanıcı arayüzü insan içindir; API makine içindir.
Web dünyasında bu genelde HTTP üzerinden çalışır: bir adrese istek gönderirsiniz, yapılandırılmış bir yanıt alırsınız. Yanıt bugün neredeyse her zaman JSON biçimindedir.
Kritik nokta, API’nin bir sözleşme olmasıdır: hangi adrese ne gönderirseniz ne alacağınız tanımlıdır. Arayüz değişmediği sürece arkadaki sistem değişebilir.
REST’in fikri
REST bir protokol değil, bir tasarım yaklaşımıdır. Temel fikri kaynakları adreslerle ifade etmektir.
Bir kullanıcı listesi /kullanicilar, tek bir kullanıcı /kullanicilar/42 adresiyle temsil edilir. Ne yapmak istediğinizi adres değil, HTTP metodu söyler.
Bu ayrım REST’i anlamanın anahtarıdır: adres neyi, metot ne yapacağınızı belirtir.
Metotlar
GET okur ve hiçbir şeyi değiştirmez. Aynı isteği yüz kez göndermek güvenlidir.
POST yeni kaynak oluşturur. Tekrarlamak yeni bir kayıt daha üretir — bu yüzden bir ağ hatasında körlemesine tekrar denemek risklidir.
PUT kaynağı tümüyle değiştirir. Aynı isteği tekrarlamak sonucu değiştirmez; idempotandır.
PATCH kısmi güncelleme yapar. DELETE siler.
GET ile POST arasındaki fark yalnızca biçimsel değildir: GET istekleri önbelleklenebilir, günlüklere adresiyle yazılır ve tarayıcı geçmişinde durur. Bu yüzden hassas veri hiçbir zaman adres içinde taşınmaz.
İdempotans kavramının yapılandırma tarafındaki karşılığı yapılandırma yönetiminde idempotans rehberinde.
Durum kodları
Yanıtın ilk bilgisi üç haneli koddur ve ilk rakamı sınıfı söyler.
2xx başarılıdır. 200 genel başarı, 201 oluşturuldu, 204 başarılı ama gövde yok.
3xx yönlendirmedir.
4xx istemci hatasıdır — yani sizin isteğinizde sorun vardır. 400 bozuk istek, 401 kimlik doğrulanmadı, 403 doğrulandı ama yetki yok, 404 bulunamadı, 429 çok fazla istek.
5xx sunucu hatasıdır. Sizde değil karşı taraftadır ve genelde tekrar denemek anlamlıdır.
401 ile 403 ayrımı otomasyonda önemlidir: birincisi belirtecin geçersiz olduğunu, ikincisi geçerli olduğu ama yetmediğini söyler. İkisine aynı tepkiyi vermek — örneğin yeniden kimlik doğrulamayı denemek — sonsuz döngü üretir.
Aynı kodları HTTP başlıkları tarafında yorumlamak için önbellek başlıkları aracına bakabilirsiniz.
Kimlik doğrulama
Üç yaygın yöntem vardır.
API anahtarı en basitidir: her isteğe bir başlıkta eklenen sabit bir dize. Kolaydır ama uzun ömürlüdür ve sızdığında iptal edilene kadar geçerlidir.
Taşıyıcı belirteç (bearer token) kısa ömürlüdür ve genelde OAuth akışıyla alınır. Süresi dolduğunda yenilenir. Kimlik katmanının nasıl kurulduğu SSO nedir yazısında.
İmza tabanlı yöntemde her istek, paylaşılan bir sırla imzalanır. Anahtar ağda hiç gitmez. Webhook doğrulamasında yaygındır; örneği webhook imza doğrulayıcı aracında.
Hangisi olursa olsun kimlik bilgisi betiğe gömülmez. Ortam değişkeninden ya da bir sır deposundan okunur; nedeni boru hattı güvenliği rehberinde.
Sayfalama ve hız sınırı
Büyük listeler tek yanıtta gelmez. API genelde sayfa sayfa döner ve yanıtta bir sonraki sayfanın işaretçisini verir.
Otomasyon yazarken bu döngüyü doğru kurmak gerekir: ilk sayfayla yetinen bir betik, sessizce eksik veri işler. “Rapor neden eksik” sorusunun sık rastlanan nedeni budur.
Hız sınırı ise belirli bir sürede kaç istek yapabileceğinizi belirler. Aşıldığında 429 alırsınız ve yanıt genelde ne kadar bekleyeceğinizi söyleyen bir başlık taşır.
Doğru tepki, o başlığı okuyup beklemektir. Sabit aralıklarla tekrar denemek sınırı daha da zorlar; üstel geri çekilme — her denemede biraz daha uzun beklemek — standart yaklaşımdır.
Webhook: ters yön
API’de siz sorarsınız. Webhook’ta karşı taraf, bir olay olduğunda sizin adresinize istek gönderir.
Bu, sürekli sorgulamaktan verimlidir. Ama uç noktanız internete açık olduğu için gelen isteğin gerçekten o sistemden geldiğini doğrulamanız gerekir — imza denetimi bu yüzden zorunludur.
İki ayrıntı sık atlanır: imza ham gövde üzerinden hesaplanmalıdır (ayrıştırılmış hâl üzerinden değil), ve karşılaştırma sabit sürede yapılmalıdır.
Yanıtı işlemek
JSON yanıtları elle ayrıştırmak yerine dilin kendi araçları kullanılır. PowerShell tarafında yanıt doğrudan nesneye dönüşür; bu, boru hattında süzmeyi kolaylaştırır.
Gelen yapıdan şema ya da tür tanımı çıkarmak için JSON şema üreteci aracını, biçimlendirmek ve hatalı JSON’da sorunu bulmak için JSON biçimlendirici aracını kullanabilirsiniz.
Kısaca
REST API’de adres kaynağı, metot işlemi, durum kodu sonucu söyler. 4xx sizde, 5xx karşı tarafta bir sorun olduğunu anlatır.
Otomasyon yazarken üç şeyi atlamayın: sayfalamayı sonuna kadar takip edin, hız sınırında üstel geri çekilme uygulayın ve kimlik bilgisini koda gömmeyin.