Herkese açık bir API tasarlamak
Bir API'yi uzun ömürlü bir sözleşme olarak tasarlamak — sürümlenmiş, belgelenmiş ve kullanıcıları için istikrarlı.
Bu nedir? · Uygulama kılavuzu
Tekrarlanan bir teknik sorunun çözümü için uygulama kılavuzu. Başlangıç koşullarını, adımları, karar noktalarını ve sonucu doğrulama yöntemini açıklar. Genel bakışa git
Bu kılavuz ne zaman geçerli?
Bir API iş ortakları, mobil uygulamalar veya birden fazla frontend tarafından kullanılacaktır. Dahili koddan farklı olarak herkese açık bir arayüz bir taahhüttür: Değişiklikler, kontrol etmediğiniz harici sistemleri etkiler.
Hedefler
- API, kullanıcıları için istikrarlı ve öngörülebilir kalır.
- Mevcut entegrasyonları bozmadan gelişebilir.
- Belgelenmiştir ve ek soru sormaya gerek kalmadan kullanılabilir.
Tipik riskler
- Entegrasyonları sessizce bozan breaking change'ler.
- Dahili veri modellerini dışarıya olduğu gibi aktarmak — sıkı bağımlılık.
- Tekrarlanan çağrılarda eksik idempotency.
- Belirsiz hata ve durum semantiği.
Geliştirmeye başlamadan önce.
- Kullanıcıları ve gerçek kullanım senaryolarını anlamak — dahili yapıyı yansıtmak değil.
- Kaynakları ve aralarındaki ilişkileri veritabanından bağımsız olarak modellemek.
- v1 yayımlanmadan önce sürümleme ve kullanımdan kaldırma (deprecation) stratejisini belirlemek.
Nasıl ilerliyoruz?
API-first, bir sözleşme olarak
Arayüz önce tasarlanır ve belgelenir (örneğin OpenAPI olarak). Sözleşme, implementasyondan önce gelir.
Dışarıya karşı ayrıştırmak
Harici temsiller dahili modellerden bilinçli olarak ayrılır. Dahili değişiklikler API'yi değişmeye zorlamamalıdır.
Idempotency ve net semantik
Yazma işlemleri idempotenttir; durum kodları, hata formatları ve sayfalama tutarlı ve belgelenmiştir.
Eklemeli sürümleme
Değişiklikler mümkün olduğunca eklemelidir. Bir breaking change, net bir kullanımdan kaldırma süresiyle yeni bir sürüm anlamına gelir.
Yanıt bekleyen sorular.
Kaynak, kullanıcıların kullanım senaryosunu mu yansıtıyor — yoksa dahili tabloyu mu?
Her yazma işlemi idempotent mi?
Değişiklik eklemeli mi, yoksa yeni bir sürüm mü gerektiriyor?
Davranış, kodlanmadan önce belgelenmiş mi?
Doğrulama
- Belgeler, ek soru sormadan entegrasyon yapmak için yeterlidir.
- Contract testleri, sözleşmeyi implementasyona karşı doğrular.
- Tekrarlanan çağrılar mükerrer bir etki üretmez.
Sık yapılan hatalar
- Dahili veri modellerini birebir API olarak dışarı açmak.
- Sürümlemeyi sonradan getirmek.
- Hataları belirsiz veya tutarsız biçimde döndürmek.
- Breaking change'leri kullanımdan kaldırma süresi tanımadan devreye almak.
Ne zaman bilinçli olarak farklı ilerliyoruz?
- Yalnızca kendi servisleriniz arasındaki dahili iletişim için daha sıkı bir bağımlılık kabul edilebilir — orada sözleşmeyi değiştirmek daha ucuzdur.
- İstemcilerin verinin çok farklı kesitlerine ihtiyaç duyduğu durumlarda, katı biçimde kaynak odaklı REST yerine GraphQL'i değerlendiriyoruz.
İlgili Engineering Method aşamaları
İlgili teknik içerikleri inceleyin.
Konuyu derinleştiren kavramları, mimari kararları, uygulama kılavuzlarını ve değerlendirmeleri birlikte inceleyin.
Hizmetler
Mühendislik kararları
Bakış açıları
Benzer bir zorlukla mı karşı karşıyasınız?
Uygulama kılavuzları nasıl düşündüğümüzü gösterir. Somut projeniz için yönetimimizle görüşün: teknik düzeyde, satış konuşması olmadan.
