API odaklı bir projede ilk karar framework değil, hangi verinin hangi istemciye hangi yetkiyle sunulacağıdır. Web arayüzü, mobil uygulama ve üçüncü taraf istemciler aynı kaynağı kullanacaksa sözleşmenin açık olması bakım maliyetini azaltır.
Kaynakları ve işlemleri yazın
Örneğin içerik platformunda posts, authors ve comments kaynaklarını belirleyin. Her biri için listeleme, detay, oluşturma, güncelleme ve silme işlemlerinin gerçekten gerekli olup olmadığını sorun. URL, yöntem, istek gövdesi ve yanıt örneğini kodlamadan önce belgeleyin. Sayfalama ve filtreleme büyük listelerde baştan düşünülmelidir.
Kimlik ve yetkiyi ayırın
Kimlik doğrulama kullanıcının kim olduğunu, yetkilendirme hangi kayıt üzerinde işlem yapabileceğini belirler. Yalnızca “giriş yaptı” kontrolü yeterli değildir. Her uç noktada rol ve kayıt sahipliği senaryolarını test edin. Gizli anahtarları istemci uygulamaya gömmeyin; tarayıcı oturumu kullanılıyorsa CSRF, çerez ve CORS ayarlarını mimariyle birlikte değerlendirin.
Hata ve sürüm sözleşmesi
Başarısız istekler tutarlı durum kodu ve kullanıcıya açıklanabilir hata alanları döndürmelidir. İç sistem hatalarını ve SQL ayrıntılarını istemciye vermeyin. Kırıcı alan değişikliklerinde sürümleme veya geçiş süresi planlayın. Bir API değişikliğinin eski mobil sürümleri etkileyeceğini unutmayın. İstek kimliği, zaman ve hata sınıfıyla gözlemleme kurun; hassas veriyi loglamayın.
Yayın öncesi test
- Boş, geçersiz ve büyük girdiler.
- Yetkisiz ve başka kullanıcıya ait kayda erişim.
- Sayfalama, sıralama ve tekrar eden istekler.
- Hız sınırı, zaman aşımı ve bağımlı servis arızası.
- Yedek, geri alma ve API belge uyumu.
Kaynak: OpenAPI Specification.
