Paraşüt API’siyle çalışırken karşılaşılan sınırlar

Bu yazı geliştiricilere. Paraşüt’ün v4 API’siyle çalışan bir entegrasyon yazarken karşılaştığımız, belgelerde net yazmayan davranışları not ediyoruz. Amaç eleştiri değil — aynı duvarlara ikinci kez çarpılmasın diye.

JSON:API ve include

API, JSON:API biçimini kullanıyor: ilişkili kayıtlar cevabın gövdesinde değil, included dizisinde geliyor ve ana kayıtta yalnız kimlikleri duruyor. İyi tarafından, N+1 isteği önlüyor: fatura listesini çekerken carisini, kalemlerini ve kalemlerin ürünlerini aynı istekte alabiliyorsunuz.

Kötü tarafı: include listesi uzadıkça istek daha kırılgan hale geliyor. Bir ilişki adı yanlışsa ya da o hesapta kullanılamıyorsa, isteğin tamamı hata dönüyor — kısmi sonuç yok.

Sayfa boyu 25

page[size] için üst sınır 25. Daha büyük bir değer göndermek hata vermiyor, sessizce 25’e iniyor — bu yüzden “niye 100 kayıt gelmedi” sorusu ilk gün sorulur. Toplam sayfa sayısı meta.total_pages içinde geliyor; buna güvenebilirsiniz.

İstek kotası

On saniyede on istek. Aşınca 429 geliyor. Toplu aktarımda bu, planlamayı belirleyen tek sayı: sayfa başına 25 kayıt ve saniyede bir istek demek, dakikada yaklaşık 1.500 kayıt üst sınırı demek — ilişkiler için ek istek gerekmiyorsa.

Pratik sonuç: kullanıcıya “aktarım sürüyor” demek yetmiyor, kaçıncı sayfada olduğunu da göstermek gerekiyor. Yoksa üç dakika bekleyen kullanıcı sayfayı yeniler ve ikinci bir aktarım başlatır.

Tarih süzgeci beklendiği gibi çalışmıyor

En çok vakit kaybettiren yer burası oldu. filter[issue_date] alanına bir aralık vermenin belgelenmiş bir yolu yok. Denediğimiz aralık sözdizimi şu hatayı döndü:

400 Bad Request
{ “errors”: [ { “detail”: "’issue_date’ is not a date" } ] }

Virgülle ayırmak da çözüm değil: virgül bu API’de “şunlardan biri” anlamına geliyor (filter[item_type] öyle çalışıyor). Bir tarih aralığını virgülle yazarsanız yalnız iki uç günü süzer, aradaki günleri sessizce atlar. Hata vermediği için de fark etmezsiniz — en tehlikelisi bu.

Yaptığımız: süzmeyi tamamen bırakıp sort=-issue_date ile yeniden eskiye çekmek, aralığı istemci tarafında uygulamak ve aralığın altına inen ilk sayfada durmak. Yakın tarihler için hızlı, eski dönemler için sayfa sayısı kadar yavaş — ama doğru.

Satış faturası ile gider faturası aynı şey değil

Gider faturalarının kalemsiz gelebilmesi, hedef sistemde kalem zorunluysa sorun. Biz tek satırlık bir hizmet kalemine dönüştürüyoruz ki fatura toplamı ile kalem toplamı tutsun.

Alan uzunlukları

Kaynak sistemin izin verdiği uzunluk hedefinkinden fazlaysa, aktarım doğrulama hatasıyla durur. Bizde ürün açıklaması 100 karakterle sınırlıydı ve Paraşüt’ten 113 karakterlik bir açıklama geldiğinde aktarımın tamamı bir faturada takıldı.

Ders: aktarım yazarken hedef şemadaki her alan sınırını kaynağın verebileceği en uzun değerle karşılaştırın; kırpılacaksa nerede kırpıldığı belli olsun. Tek bir uzun metin yüzünden bin faturalık bir aktarımın yarıda kalması, kullanıcı için anlaşılmaz bir hatadır.

e-Belge durumu

Belgenin e-Arşiv mi e-Fatura mı olduğu ve GİB durumu ilişkili e-belge kaydından okunuyor. Bunu her fatura için ayrı istekle sormak kota yüzünden mümkün değil; liste isteğine dahil ederek almak gerekiyor — ve bu, yukarıdaki kademe mantığının en çok işe yaradığı yer.

Özet

• Sayfa boyu 25, kota 10 istek / 10 saniye. Planı buna göre yapın.
• Tarih aralığıyla süzmeye güvenmeyin; sıralayıp istemcide kesin.
• Virgül “aralık” değil “şunlardan biri” demek.
• include listesini kademeli deneyin.
• Gider faturalarını satış faturası gibi işlemeyin.
• Alan uzunluklarını aktarımdan önce karşılaştırın.

Bu entegrasyonun kullanıcı tarafı →