Bir müşteri CRM’ine 10 bin kişi aktarmak istiyor.
API’de sadece tekil oluşturma endpoint’i var:
POST /api/contacts
10 bin istek. Her biri 80 ms. Sırayla gönderildiğinde 13 dakikadan fazla. Paralel gönderildiğinde ise rate limit’e takılıyor.
Toplu bir endpoint gerekiyor.
Atomik mi, kısmi mi?
Batch endpoint tasarımında ilk soru şu: 500 kayıttan biri hatalıysa ne olacak?
Atomik: Ya hepsi oluşturulur ya hiçbiri. Tek bir hatalı kayıt bütün isteği reddeder.
Kısmi başarı: Geçerli kayıtlar oluşturulur, hatalı olanlar raporlanır.
Atomik yaklaşım basit ve öngörülebilir. Client için sonuç nettir. Ama 500 kayıttan birindeki hatalı bir e-posta adresi yüzünden 499 geçerli kaydın reddedilmesi, kullanıcı için sinir bozucu olabilir.
Kısmi başarı daha kullanışlı ama client’ın her kaydın sonucunu ayrı ayrı işlemesini gerektirir.
Doğru seçim kullanım senaryosuna bağlı. Bir siparişin kalemleri birlikte anlamlıdır, atomik olmalı. Bağımsız kişi kayıtları ise kısmi başarıya uygundur.
Bazı API’ler bunu client’a bırakır:
POST /api/contacts:batchCreate?atomic=true
Cevap formatı
Kısmi başarıda her kaydın sonucu, istek içindeki sırasıyla eşleştirilebilir şekilde dönmeli:
{
"results": [
{ "index": 0, "status": "created", "id": "c_8812" },
{ "index": 1, "status": "created", "id": "c_8813" },
{ "index": 2, "status": "error",
"error": { "code": "invalid_email", "field": "email" } }
],
"summary": { "created": 2, "failed": 1 }
}
Client hangi kayıtların başarısız olduğunu ve nedenini bilir. Sadece onları düzeltip tekrar gönderebilir.
HTTP status code seçimi tartışmalı. Bazı API’ler kısmi başarıda 200 döner ve detayı gövdeye bırakır. Bazıları WebDAV’dan gelen 207 Multi-Status kullanır. Hangisi seçilirse seçilsin, tutarlı olmak ve belgelemek önemli. Client, sadece status code’a bakarak bütün kayıtların başarılı olduğunu varsaymamalı.
Tekrarlanan istek
Bir batch isteği timeout aldı. Client tekrar gönderdi.
Kayıtların bir kısmı ilk istekte oluşturulmuşsa, ikinci istekte tekrar oluşturulur.
Batch işlemlerde idempotency daha da önemli. İsteğin tamamı için bir idempotency key veya her kayıt için client’ın ürettiği bir referans, tekrar gönderimde kopya oluşmasını engeller.
Sınırlar
Bir batch endpoint’i sınırsız boyutta istek kabul etmemeli.
max 500 items per request
max 5 MB body
Çok büyük istekler uzun süren transaction’lar, bellek baskısı ve timeout’lar demek. Sınırı aşan istekler 413 ile reddedilir ve client parçalara bölerek gönderir.
Daha büyük hacimler için, örneğin 1 milyon kayıt, senkron bir batch endpoint yerine dosya yükleme ve asenkron işleme daha uygun. Client bir CSV dosyası yükler, bir iş başlatılır, sonuç bir rapor olarak sunulur.
Rate limiting
Batch endpoint’leri tekil endpoint’lerle aynı rate limit’e tabi tutmak yanlış sonuç verir. 500 kayıtlık bir istek, 1 kayıtlık bir istekle aynı maliyette değildir.
Rate limit’i istek sayısı yerine kayıt sayısı üzerinden hesaplamak, batch endpoint’inin limitleri aşmanın bir yolu olarak kullanılmasını engeller.
Batch endpoint’ler performans için eklenir.
Ama asıl tasarım zorluğu performans değil, işler kısmen ters gittiğinde client’a ne söyleneceği.
