Uygulama kılavuzu · API'ler

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

Sürekli karşılaşılan bir problem için standart bir süreç — durum, adımlar, karar kriterleri ve validasyon. Neden uyguladığımız değil, nasıl uyguladığımız. Genel bakışa git

Durum

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 yabancı 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.

Hazırlık

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.

Mühendislik yaklaşımı

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 mükerrer işlemleri önleyen (idempotent)tir; 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.

Karar noktaları

Yanıt bekleyen sorular.

Kaynak, kullanıcıların kullanım senaryosunu mu yansıtıyor — yoksa dahili tabloyu mu?
Her yazma işlemi mükerrer işlemleri önleyen (idempotent) mi?
Değişiklik eklemeli mi, yoksa yeni bir sürüm mü gerektiriyor?
Davranış, implemente edilmeden ö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.

Karşı sınama

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.

Proje sürecindeki ilgili çalışma yöntemleri

Problemi çerçevelemek Alanı modellemek Temel kararları vermek Kritik yolu sınamak

Okumaya devam edin