Bir API tasarlarken önce neyi sadeleştiririm?

Bir API'nin kullanımı yalnız endpoint adlarından oluşmuyor. Hata biçimi, erişim sınırları ve bir işlemin tekrarlandığında ne olduğu da sözleşmenin parçası.

Kaynağın adını doğru koymak

İlk sorum genellikle şu: Bu uç nokta neyi temsil ediyor? Bir görevi mi, çalışma alanını mı, bir üyeliği mi? Kaynakları açık tanımlamak, sonradan eklenecek işlemlerin de anlaşılır kalmasını sağlıyor.

Her davranışa yeni bir endpoint eklemeden önce, bunun mevcut bir kaynağın durum değişikliği olup olmadığını düşünüyorum. Amaç en az sayıda adres üretmek değil, tahmin edilebilir bir yapı kurmak.

Güven sınırı sunucudadır

Arayüzün bir düğmeyi gizlemesi yetkilendirme değildir. Her istek sunucuda doğrulanmalı; kullanıcının ilgili kaynağa erişimi ayrıca kontrol edilmelidir.

• Kimlik doğrulama ile kaynak yetkisini ayrı değerlendir.
• Girdi biçimini ve kabul edilen değerleri doğrula.
• Birbirine bağlı veri değişikliklerini transaction içinde tut.
• Hata yanıtlarında iç sistem ayrıntılarını açığa çıkarma.

Hataları da tasarlamak

Geçersiz bir alan adı ile geçici bir servis kesintisi aynı şekilde ele alınmamalı. İstemcinin sorunu anlayabileceği bir durum kodu ve güvenli bir açıklama, gereksiz tahminleri azaltır.

Küçük bir sözleşme, sağlam bir temel

İlk sürümde sayfalama, işlem sınırları ve hata biçimini yazılı hale getirmek sonradan düzeltme maliyetini düşürür. Buna karşılık henüz bir ihtiyaca karşılık gelmeyen soyutlamalar, API'yi olduğundan karmaşık gösterebilir.