Yapay Zekâ ile API Geliştirirken Kaliteyi Korumak
Sayfayı kopyala
💡 Özet (TL;DR):
- Koddan önce: Agent'tan iş sürecini, kaynak modelini, erişim sınırlarını, hata davranışını ve sözleşme değişikliğini açıklamasını isteyin; eksik bilgiyi varsayımla doldurmasına izin vermeyin.
- Review sırasında: HTTP metotlarını, tekrar deneme davranışını, kayıt sahipliğini, hata sözleşmesini, gereğinden geniş veri erişimini ve geriye dönük uyumluluğu bağımsız bir bağlamda kontrol edin.
- Teslimattan önce: OpenAPI doğrulamasını, sözleşme ve kırılma testlerini, negatif yetki testlerini ve dokümantasyon eşleşmesini pipeline'da zorunlu kılın. İşletme kararlarının sahipliği yine insanlarda kalmalı.
2021'de bu sitede yedi yazılık bir REST serisi hazırladım: “RESTful API Bileşenleri”, “REST API Tasarım İncelikleri”, “REST API URI Yapısı Nasıl Olmalı?”, “REST API Hata Yönetimi”, “REST API Kimlik Doğrulama Nasıl Yapılır?”, “REST API Güvenliği Nasıl Sağlanır?” ve “REST API Dokümantasyonu Nasıl Oluşturulur?”.
Bu yazılardaki temel ilkelerin çoğu bugün de geçerli. Seriyi kaldırma kararım, bu ilkelerin artık yanlış olmasıyla ilgili değil. Seri, geliştiricilerin konuları sırayla okuyup REST kararlarını öğrendikten sonra kod yazacağı bir çalışma biçimine göre hazırlanmıştı.
Bugün pek çok geliştirici ne istediğini AI coding agent'a birkaç cümleyle anlatıp çıkan kod üzerinden ilerliyor. Eski yazıları ayrı ayrı tutmak, doğru bilgiyi artık daha az kullanılan bir öğrenme yolunun içinde bırakıyordu. O yazıları kaldırmaya, yerine bu okuduğunuz yazıyı yazmaya karar verdim.
Bu yazıda eski serinin tamamını yeniden anlatmayacağım. Oradaki prensipleri AI ile API geliştirirken kullanabileceğimiz üç yere taşıyacağım: başlangıç promptu, kod incelemesi ve teslimat kontrolleri.
Bir REST API promptu neden eksik kalır?
Agent'a “müşteri kayıtları için CRUD API yaz” dediğinizde birkaç dakika içinde çalışan endpoint'ler alabilirsiniz. Fakat çalışan kod şu soruları cevaplamaz:
- Müşteri kaydı fiziksel olarak silinebilir mi, arşivlenir mi, anonimleştirilir mi?
- Aynı silme isteği iki kez gelirse ne olur?
- Bir kullanıcı başka bir müşterinin kaydını hangi koşulda görebilir?
- Mobil uygulamanın kullandığı mevcut yanıt değişirse kim etkilenir?
- Hata alan istemci isteği yeniden deneyebilir mi?
REST kalitesinin ilk adımı bu kararları vermektir. URI ve uygulama kodu daha sonra gelir. Agent, eksik bırakılan yerleri çoğu zaman makul görünen varsayımlarla doldurur. Böylece teknik bir tercih, fark edilmeden işletmenin veri saklama, erişim veya entegrasyon kararına dönüşebilir.
Koddan önce agent'a verilecek talimat
Aşağıdaki metin, yeni bir API veya endpoint çalışmasının başına konabilecek kısa bir başlangıç talimatıdır:
Henüz kod yazma. Önce bu API değişikliği için:
1. İş sürecini, kaynağın sahibini ve beklenen sonucu açıkla.
2. Kaynakları, aralarındaki ilişkileri ve önerdiğin URI yapısını çıkar.
3. Her endpoint için HTTP metodunu, yan etkilerini ve aynı isteğin
tekrarında ne olacağını belirt.
4. Başarılı yanıtları, hata durumlarını ve istemcinin hangi hatada ne
yapması gerektiğini tanımla.
5. Kimlik doğrulama, yetkilendirme, rol, tenant ve kayıt sahipliği
kontrollerini ayrı ayrı göster.
6. Girdi doğrulama, döndürülecek alanlar, istek boyutu, istek sınırı,
loglama ve hassas veri risklerini listele.
7. Mevcut OpenAPI sözleşmesine önerdiğin farkı ve geriye dönük kırılma
riskini göster.
8. Yeni bir veri tabanı, cache, queue veya servis öneriyorsan hangi
somut ihtiyacı çözdüğünü ve işletim maliyetini açıkla.
Eksik bilgi varsa varsayım yapma. Soruları listele ve bekle.
Bu talimat agent'a REST öğretmiyor. Koddan önce hangi kararların görünür olması gerektiğini söylüyor. Ürün sahibinin cevaplaması gereken silme veya saklama kararının teknik bir varsayım gibi uygulanmasını da önlüyor.
Eski REST prensiplerini AI ile nasıl koruyacağız?
Eski serideki ayrıntıları yedi kontrole indirdiğimde ortaya şu tablo çıkıyor:
| Prensip | Agent'a söyle | Review sırasında kontrol et |
|---|---|---|
| Bileşen ve mimari | İhtiyaç kanıtlanmadan yeni veri tabanı, cache, queue, servis veya framework ekleme. Her bileşenin çözdüğü problemi ve işletim maliyetini yaz. | Eklenen her bağımlılık gerçek bir yük, güvenilirlik veya entegrasyon ihtiyacına dayanıyor mu? Ekip bunu işletebilir mi? |
| Kaynak ve URI tasarımı | URI'leri iş alanındaki kalıcı kaynaklardan türet. İsimlendirme, çoğulluk, küçük harf ve alt kaynak kuralını mevcut API ile tutarlı uygula. | URI ve HTTP metodu birlikte okununca işlem anlaşılıyor mu? Aynı kaynak başka endpoint'lerde farklı adlandırılmış mı? |
| HTTP metotları | Her endpoint için güvenli, tekrarlandığında aynı sonucu üreten ve yeniden denenebilen davranışı açıkla. Yan etkisi olan işi GET altında saklama. | Tekrarlanan istek aynı işlemi iki kez doğuruyor mu? GET durum değiştiriyor mu? PUT, PATCH ve DELETE davranışı sözleşmeyle uyumlu mu? RFC 9110 bu anlamları tanımlar. |
| Hata yönetimi | Bütün endpoint'lerde ortak, makine tarafından okunabilir hata biçimi kullan. Durum kodu, güvenli mesaj, alan hataları, problem kodu ve request ID tanımla. | 401, 403, 404, 422, 429 ve 5xx yanıtları doğru ayrılmış mı? Stack trace veya hassas bilgi sızıyor mu? İstemci hatadan sonra ne yapacağını anlayabiliyor mu? RFC 9457 ortak problem yanıtı biçimini verir. |
| Kimlik ve yetki | Kimlik doğrulama, fonksiyon yetkisi ve kayıt sahipliği kontrollerini ayrı tasarla. Rol, scope, tenant ve nesne sahipliği kurallarını endpoint bazında yaz. | Geçerli token taşıyan kullanıcı başka bir kullanıcının veya tenant'ın kaydına ID değiştirerek erişebiliyor mu? Yönetici endpoint'i sıradan kullanıcıya açılmış mı? |
| Güvenlik ve kötüye kullanım | Tüm girdileri şemayla doğrula. Yazılabilir ve döndürülebilir alanları açıkça sınırla. İstek boyutu, istek sınırı, secret kullanımı, loglama ve kötüye kullanım senaryolarını ele al. | Fazladan alan göndererek korunan veri değiştirilebiliyor mu? Gereğinden fazla veri dönüyor mu? Negatif yetki, kaynak tüketimi ve hassas iş akışı testleri var mı? OWASP API Security Top 10 review için iyi bir başlangıç listesi sunar. |
| Sözleşme ve dokümantasyon | Uygulama kodundan önce OpenAPI farkını hazırla. İstek, yanıt, hata, güvenlik ve istek sınırı davranışlarını örneklerle tanımla. | Kod ile sözleşme eşleşiyor mu? Değişiklik mevcut istemcileri kırıyor mu? Dokümantasyon ve yayımlanan sözleşme aynı sürümde mi? OpenAPI bu ortak sözleşmenin biçimini tanımlar. |
HATEOAS'tan burada korunması gereken dar prensip şu: Bir sonraki geçerli aksiyon iş akışının parçasıysa, yanıt bunu istemciye tahmin ettirmemeli. AI ile API geliştirirken linkler veya aksiyon imaları JSON içinde agent'ın doğaçlamasına bırakılmamalı; sözleşme kararı olarak görünür olmalı.
Bu tablo bir API geliştirme kuralı olarak kullanılabilir. Bütün API işleri için geçerli maddeler kod deposundaki kalıcı agent talimatına yazılır. Ürüne veya endpoint'e özgü kararlar ise iş tanımında ve OpenAPI sözleşmesinde tutulur.
Review için ikinci agent'a verilecek talimat
Kodu üreten agent'a “bir de kendini kontrol et” demek yararlı olabilir. Fakat aynı bağlamda çalışan agent, kendi varsayımını hata olarak görmeyebilir. Review'u ayrı bir görev ve mümkünse ayrı bir agent bağlamı olarak çalıştırmak daha güçlü bir kontrol sağlar.
Bu API değişikliğini bağımsız reviewer olarak incele. Henüz kodu değiştirme.
Uygulayan agent'ın açıklamasını kanıt kabul etme; mevcut OpenAPI sözleşmesini,
kod deposundaki kuralları ve testleri esas al.
Şunları kontrol et:
- Kaynak modeli ve URI'ler mevcut API ile tutarlı mı?
- HTTP metotları, yan etkiler ve tekrar deneme davranışı doğru mu?
- Başarı ve hata yanıtları sözleşmeyle eşleşiyor mu?
- Kimlik doğrulama, fonksiyon yetkisi, tenant ve kayıt sahipliği ayrı ayrı
uygulanmış mı?
- Girdi, yazılabilir alanlar ve dönen veri gereğinden geniş mi?
- Mevcut istemcileri kıracak bir sözleşme değişikliği var mı?
- Başarılı akışın yanında negatif yetki, doğrulama, istek sınırı ve tekrar
deneme testleri var mı?
Her bulgu için etkilenen endpoint'i, kanıtı, riski ve gerekli testi yaz.
Review onaylanmadan düzeltme yapma.
Burada review'un amacı kod biçimini düzeltmek değil. Agent'ın işletme kararını yanlış yorumladığı, REST davranışını bozduğu veya güvenlik sınırını atladığı yeri bulmaktır.
Pipeline hangi hataları otomatik durdurmalı?
Prompt ve review tek başına yeterli değil. Tekrarlanabilir kurallar pipeline'a girmediğinde aynı hata başka bir değişiklikte yeniden ortaya çıkar. En az şu dört kontrol otomatik çalışmalıdır:
- OpenAPI sözleşmesi geçerli mi ve uygulamayla eşleşiyor mu?
- Sözleşme farkı geriye dönük kırılma yaratıyor mu?
- Sözleşme testleri ile negatif yetki, doğrulama ve tekrar deneme testleri geçiyor mu?
- Yayımlanan dokümantasyon sözleşmeyle aynı sürümde mi?
Erişim modelini, ödeme davranışını, hassas veriyi, veri silme politikasını veya mevcut istemcileri etkileyen değişiklikler ayrıca adı belli bir insanın onayında durmalı. Bir başka agent'ın “uygun” demesi bu kararların sahipliğini üstlenmez.
Eski seri neden artık tek yazı?
Eski seri, geliştiricinin REST bilgisini öğrenmesini hedefliyordu. Bugünkü ihtiyaç, bu bilginin AI destekli geliştirme akışında kaybolmamasını sağlamak.
Bu nedenle yedi ayrı yazı yerine tek bir kontrol akışı daha yararlı:
- İş kararını verin.
- Agent'a eksik kararları sordurun.
- Sözleşmeyi koddan önce görün.
- Uygulamayı bağımsız review'dan geçirin.
- Tekrarlanabilir kuralları pipeline'da zorunlu kılın.
Bir ekip bu kontrolleri promptta, kod deposundaki talimatlarda ve pipeline'da görünür kılamıyorsa eski REST bilgisini yeni çalışma biçimine taşımamış demektir. Agent kodu hızlı yazabilir. API'nin neye söz verdiğine ve hangi riski alamayacağına hâlâ insanlar karar verir.
