API geliştirme
Web uygulamaları, mobil uygulamalar ve bağlı sistemler için belgelenmiş, sürümlenmiş arayüzler — sistem altyapınızın geri kalanının üzerine kurulduğu temel.
Erken fark ettiğimiz riskler.
Bu tür sistemlerde sık karşılaşılan riskleri, erken uyarı işaretlerini ve aldığımız önlemleri açıklıyoruz.
- 01
Fark edilmeyen uyumluluk değişikliği
- Neden
- Bir alanın yeniden adlandırılması veya doğrulamanın sıkılaştırılması küçük bir düzeltme gibi görünebilir. Ancak API’yi kullanan harici sistemler için geriye dönük uyumsuzluk yaratabilir.
- Erken uyarı işaretleri
- Eklemeli genişletmeler yerine mevcut yapıda değişiklikler; herkese açık sözleşmeye karşı otomatik test yok; hatayı kendi izleme sisteminizden önce çağıran taraf bildiriyor.
- Nasıl önlüyoruz
- Mümkün olan yerde eklemeli genişletmek. Herkese açık sözleşme yayına almadan önce otomatik olarak test edilir; yeni bir sürüm gerekirse eskisi dokunulmadan geçerli kalır.
- Avantajlar ve sınırlamalar
- Bedeli: Contract testleri ve mevcut yapıyı değiştirmekte temkinlilik. Farklı durum: Arayüz tamamen dahiliyse ve çağıranlarıyla birlikte yayına alınıyorsa sözleşmeyi değiştirmek ucuzdur.
- 02
Sözleşmesi olmayan hatalar
- Neden
- Hata yanıtları da API sözleşmesinin bir parçasıdır. Sürekli değişen serbest metin mesajları, istemcileri mesaj içeriğine göre karar vermeye zorlar.
- Erken uyarı işaretleri
- Kararlı, sınıflandırılmış bir kod yok; istemci ve sunucu hataları ayırt edilemiyor, dolayısıyla kimse tekrar mı denemesi yoksa düzeltme mi yapması gerektiğini bilmiyor; mesajlarda dahilî ayrıntılar.
- Nasıl önlüyoruz
- Kararlı, makine tarafından değerlendirilebilir hata kodları, çağıranın hatası ile sağlayıcının hatası arasında net bir ayrım ve yanıtta dahilî iz bırakılmaması.
- Avantajlar ve sınırlamalar
- Bedeli: Başarılı yanıtlarla aynı özenle bakımı yapılması gereken ek bir sözleşme alanı. Farklı durum: Birlikte büyüyen tek bir kullanıcısı olan dahilî bir arayüzde hata modeli daha yalın kalabilir.
- 03
API sözleşmesini iç uygulamayla karıştırmak
- Neden
- Bir arayüzün arkasındaki sağlayıcı değiştirilebilir; o arayüzden akıp kalıcı hâle gelen veriler ise değiştirilemez. Kendi bakış açısını bir sağlayıcının yapısına bağlayan, her değişikliği mevcut verilere kadar hisseder.
- Erken uyarı işaretleri
- Kendi veri modeli harici bir hizmetin yapısını izliyor; sağlayıcı değişikliği, mevcut verilerin dönüştürülmesi olarak değil, bir bağlantı meselesi olarak planlanıyor.
- Nasıl önlüyoruz
- Veriler, sistemin kendi veri modelinde tutulur. Harici servisler, sağlayıcı değişse de korunabilen bir entegrasyon katmanı üzerinden bağlanır.
- Avantajlar ve sınırlamalar
- Bedeli: Doğrudan geçiş yerine bir çeviri katmanı ve kontrollü biçimde taşınmış mevcut veriler. Farklı durum: Mevcut veriler küçük ve kritik değilse ve yeniden temin edilmeleri ucuzsa.
Koddan önce sorduğumuz sorular.
Mimariyi belirlemek için önce ihtiyaçlarınızı ve kısıtlarınızı netleştiriyoruz. Aşağıdaki sorular teknik kararlarımızın temelini oluşturur.
- 01
İletişim hangi biçimde — nesneler, eylemler mi, yoksa esnek sorgular mı?
- Neden önemli
- Stil sözleşmeyi şekillendirir ve sözleşmeyi değiştirmek zordur. Modaya göre karar vermek, bir uygunluk sorusunu zevk meselesi gibi ele almak demektir.
- Tipik sonuç
- Adlandırılmış nesneler REST'e, bilinen sistemler arasındaki eylemler RPC'ye, çok sayıda çağıranın çok farklı veri kesitlerine ihtiyaç duyması GraphQL'e götürür. Emin olunamadığında: on yıl sonra da anlaşılacak ve bilen ekip bulunabilecek en yaygın stil.
- 02
Arayüz çağıranın iş alanını mı ifade ediyor — yoksa dahilî uygulamayı mı?
- Neden önemli
- Bir kullanıcının gözlemlediği her şey sözleşmeye dönüşür. Aynen yansıtılan dahilî yapılar, harici sistemleri serbestçe değiştirmek istediğiniz kararlara bağlar.
- Tipik sonuç
- Dış temsili dahilî modelden ayrı tasarlıyor ve sınırda çeviri yapıyoruz. Kısa ömürlü bir prototipte buna gerek kalmaz.
- 03
Bir işlem durumu veya parayı değiştiriyor mu?
- Neden önemli
- Bir API ağ üzerinden erişilebilir olduğu anda aynı istek eninde sonunda iki kez gelir. Bu bir hata değil, dağıtık iletişimin bir özelliğidir.
- Tipik sonuç
- Bu durumda işlem idempotent tasarlanır: her mantıksal işlem için benzersiz bir anahtar, etkiyle aynı transaction içinde kontrol edilir ve kalıcı olarak kaydedilir. Okuma işlemleri ve doğası gereği idempotent işlemler buna ihtiyaç duymaz.
- 04
Mevcut bir çağıran planlanan değişikliği fark edebilir mi?
- Neden önemli
- Cevap evetse değişiklik kırıcıdır — ne kadar küçük görünürse görünsün. Sonradan sıkılaştırılmış bir doğrulama da bir kırılmadır.
- Tipik sonuç
- Mümkün olan yerde değişikliği eklemeli olarak çözüyoruz. Mümkün değilse yeni bir sürüm oluşur, eskisi dokunulmadan geçerli kalır ve kapatma, belirli bir son tarih yerine önceden duyurulan bir deprecation sürecini izler.
Bu hizmet nedir, neleri kapsar?
Bir API; web uygulamalarının, mobil uygulamaların, iş ortaklarının ve ERP veya CRM gibi bağlı sistemlerin birbiriyle iletişim kurduğu arayüzleri sağlar. Batunet API'leri uzun ömürlü sözleşmeler olarak tasarlar — sürümlenmiş, belgelenmiş ve kararlı; böylece diğer her şey güvenle üzerine kurulabilir.
Hizmet kapsamı
- API tasarımı (REST, GraphQL)
- Kırılma olmadan sürümleme
- Kimlik doğrulama ve rate limiting
- Dokümantasyon ve geliştirici deneyimi (developer experience)
- Güvenilir webhook'lar ve olaylar (event)
Geliştirme yaklaşımımız: Batunet Engineering Method.
İhtiyaçların netleştirilmesinden uzun vadeli bakım ve işletime uzanan yedi aşamalı çalışma yaklaşımımız.
- 01
FrameProblemi netleştirme
Herhangi bir çözüm düşünülmeden önce asıl problem, sınırları ve ölçülebilir bir başarı tanımı belirlenir.
- 02
ModelModelleme
İş alanını (domain) ortak ve açık bir dille modelliyor, farklı sorumlulukları ayrı bağlamlarda tanımlıyoruz.
- 03
DecideKarar
Temel mimari kararları, değişiklik maliyeti henüz düşükken değerlendirir ve gerekçeleriyle birlikte belgeleriz.
- 04
ProveKanıtlama
Kapsamı genişletmeden önce çalışan bir temel kurar, mimariyi en riskli iş akışı üzerinde doğrularız.
- 05
BuildGeliştirme
Doğrulanmış temel üzerinde küçük, test edilebilir ve geri alınabilir adımlarla geliştiririz. İlerleme her hafta görünür olur.
- 06
HardenSağlamlaştırma
Hata senaryolarını, yükü ve güvenliği test ediyoruz. Sistemin normal koşulların yanı sıra sorun anlarında da nasıl davrandığını doğruluyoruz.
- 07
Operateİşletim
Sistemi işletir, izler ve geliştirmeye devam ederiz — ve onu anlaşılır ve değiştirilebilir tutarız.
Projenize sağladığımız katkılar.
- 01
Kırılmadan gelişen arayüzler
- 02
İş ortakları ve diğer sistemler için kararlı bir temel
- 03
Başkalarının hemen çalışmaya başlayabileceği dokümantasyon
Ne zaman uygun — ne zaman değil?
Dürüst yanıt, danışmanlığın bir parçasıdır. Soruna uyan yolu öneririz.
Uygun
- Birden fazla çağıran aynı iş mantığını paylaşıyor — frontend'ler, mobil uygulamalar veya iş ortakları. İkinci çağırandan itibaren arayüz bir uygulama ayrıntısı değil, bir sözleşmedir.
- Mevcut iş mantığı, harici sistemleri iç yapıya bağlamadan kontrollü biçimde erişilebilir hâle getirilmeli.
- Harici bir hizmetin değiştirilebilir kalması gerekiyor. Önüne konan kendi arayüzünüz, kalıcı olanı değiştirilecek olandan ayırır.
- Arayüz, kullanıcılarının canlı sistemlerini bozmadan yıllar boyunca eklemeli olarak büyümeli.
Uygun değil
- Birlikte geliştirilen ve birlikte yayına alınan iki kendi servisiniz. Orada sözleşmeyi değiştirmek ucuzdur — daha sıkı bir bağlılık savunulabilir.
- Birlikte geliştirilen ve koordine edilen tek bir istemci. Bu durumda sözleşme yönetimi daha yalın tutulabilir; kapsamlı uyumluluk ve kullanımdan kaldırma süreçleri özellikle bağımsız harici istemcilerde önem kazanır.
- Bir prototip veya kısa ömürlü API. İç veri yapılarını doğrudan kullanmak daha hızlı olabilir; ayrı bir sözleşme katmanı, uzun vadeli kullanımda daha çok değer sağlar.
API geliştirme hakkında sorular
REST mi, GraphQL mi?
Kararlı ve önbelleğe alınabilir kaynaklar için REST; istemciler farklı veri kesitlerine ihtiyaç duyuyorsa GraphQL. Çoğu projede REST, ihtiyaçları karşılayan daha sade seçenektir.
Breaking change'lerden nasıl kaçınıyorsunuz?
Bilinçli sürümleme, eklemeli değişiklikler ve net sözleşmelerle. Bir API, kullanıcılarına verilmiş bir sözdür.
İlgili teknik içerikleri inceleyin.
Konuyu derinleştiren kavramları, mimari kararları, uygulama kılavuzlarını ve değerlendirmeleri birlikte inceleyin.
Mühendislik kararları
Uygulama kılavuzları
