V1

Bulbulustur API, çok sayıda mağaza ve entegrasyonun birlikte çalışmasını desteklemek üzere tasarlanmıştır. Bu nedenle API işlemlerinde veri miktarı, kayıt sayısı, istek boyutu ve eşzamanlı işlem gibi çeşitli kullanım sınırları uygulanabilir. Bu sayfa, API entegrasyonlarının kaynak sınırlarını dikkate alarak geliştirilmesi için temel prensipleri açıklar. İstek hızı sınırları ile kaynak kullanım sınırları birbirinden farklıdır. İstek Limitleri: Belirli bir zaman aralığında gönderilebilecek API isteği sayısını açıklar. Limitler: Tek bir istekte işlenebilecek veri miktarı, kayıt sayısı ve işlem kapsamı gibi sınırlamaları ele alır. API'nin tüm endpointleri aynı kullanım sınırlarına sahip olmak zorunda değildir. Kesin sayısal değerler ilgili API endpointinin teknik referansında belirtilir. Bu sayfada açıkça belirtilmemiş bir sayısal sınırın bulunmadığı varsayılmamalıdır.

Büyük veri kümeleriyle çalışan entegrasyonların listeleme işlemlerinde sayfalama kullanması önerilir. Sayfalama, tek bir istekte alınan kayıt miktarını sınırlandırarak yanıt süresinin ve kaynak tüketiminin kontrol edilmesine yardımcı olur. Sayfalama destekleyen endpointlerde kullanılan parametreler, ilgili API referansında açıklanır. Örnek sayfalama kavramları: page: İstenen sayfa numarasını belirtir. pageSize veya size: Bir sayfada istenen kayıt sayısını belirtir. Bu parametre adları genel örneklerdir. Kullanılacak kesin parametre adları endpoint sözleşmesine bağlıdır. ÖNERİLEN KULLANIM 1. İlk sayfadan başlayın. 2. Desteklenen sayfa boyutunu kullanın. 3. Yanıtı işledikten sonra sonraki sayfayı isteyin. 4. Daha fazla kayıt kalmadığında işlemi sonlandırın. 5. Mümkünse filtre kullanarak alınan veri miktarını azaltın. Bütün kayıtları tek istekte alacağınızı varsaymayın. MAKSİMUM SAYFA BOYUTU Bulbulustur API genelinde geçerli tek bir maksimum sayfa boyutu bu dokümanda ilan edilmemiştir. Sayfa boyutunun üst sınırı ve varsayılan değeri her endpoint için ayrıca tanımlanmalıdır. Not: Bazı ürün ve sipariş işlemlerinde sayfalama desteği bulunmaktadır. Bunun bütün endpointlerde aynı parametre ve sınırlarla çalıştığı varsayılmamalıdır.

API isteklerinde gönderilen veri miktarı sunucu kaynaklarını, ağ trafiğini ve işlem süresini etkiler. Özellikle büyük JSON gövdeleri, çok sayıda ürün özelliği ve dosya yükleme işlemleri için veri boyutu sınırları önemlidir. Değerlendirilebilecek sınırlar: • Maksimum HTTP request body boyutu • Maksimum dosya yükleme boyutu • Maksimum JSON nesne veya dizi elemanı sayısı • Metin alanlarının maksimum karakter uzunluğu • URL ve sorgu parametresi sınırları • İstek zaman aşımı süreleri Bu değerler API endpointine ve kullanılan altyapıya göre değişebilir. ÖNEMLİ Bulbulustur API için bütün endpointlerde geçerli ortak bir maksimum payload veya dosya boyutu bu sayfada ilan edilmemektedir. Kesin teknik değerler ilgili API referansında yayımlandığında bağlayıcı olacaktır. Entegrasyon geliştirirken gereksiz alanları göndermeyin. Büyük veri kümelerini mümkünse daha küçük işlem gruplarına ayırın. HTTP 413 Payload Too Large gibi yanıtların kullanımı, ilgili endpoint ve sunucu yapılandırmasına bağlıdır.

E-ticaret entegrasyonlarında ürün aktarımı, stok senkronizasyonu ve fiyat güncellemeleri çok sayıda kayıt üzerinde işlem yapılmasını gerektirebilir. Toplu işlem desteği bulunan endpointlerde tek bir istekte işlenebilecek kayıt sayısı sınırlanabilir. Olası kullanım alanları: • Ürünlerin toplu aktarılması • Ürün fiyatlarının güncellenmesi • Stok miktarlarının eşitlenmesi • Çoklu kayıt durumlarının değiştirilmesi İlgili endpoint toplu işlem desteklemiyorsa birden fazla kaydın tek istekte gönderilebileceği varsayılmamalıdır. ÖNERİLEN YAKLAŞIM 1. Endpointin toplu işlem desteğini kontrol edin. 2. Belgelenmiş maksimum kayıt sayısını aşmayın. 3. Büyük veri kümelerini kontrollü gruplara ayırın. 4. Her grubun sonucunu ayrı takip edin. 5. Başarısız kayıtların nedenlerini inceleyin. 6. Tekrar gönderimlerde mükerrer işlem riskini değerlendirin. Toplu isteğin HTTP düzeyinde başarılı olması, bütün kayıtların ayrı ayrı başarıyla işlendiğini garanti etmeyebilir. Her endpointin yanıt sözleşmesini esas alın. Maksimum toplu kayıt sayısı, ilgili API referansında ayrıca belirtilecektir.

Eşzamanlı işlem sayısı, aynı anda çalışmakta olan API isteklerini ifade eder. Bu kavram istek hızı sınırından farklıdır. Bir uygulama, belirli bir saniyede az sayıda istek göndermesine rağmen uzun süren işlemler nedeniyle çok sayıda aktif isteğe sahip olabilir. Özellikle aynı kaynağa yönelik paralel güncellemeler veri tutarlılığı açısından dikkat gerektirir. Örneğin aynı ürün için eşzamanlı stok güncellemeleri yapılması, entegrasyonun işleyişine bağlı olarak beklenmeyen sonuçlar doğurabilir. ÖNERİLER • Aynı kaynağa yönelik yazma işlemlerini kontrollü sıraya koyun. • Gereksiz paralel isteklerden kaçının. • İstemci tarafında eşzamanlı işlem sayısını sınırlayın. • Her işlem için makul timeout süreleri kullanın. • Başarısız işlemleri yeniden denemeden önce son durumu kontrol edin. • Dağıtık worker kullanan entegrasyonlarda ortak işlem koordinasyonu sağlayın. Bulbulustur API genelinde ayrı bir sayısal concurrency limiti bu sayfada ilan edilmemiştir. Belirli endpointler için eşzamanlı işlem sınırı tanımlanırsa ilgili API referansında açıklanacaktır. Bu bölümdeki öneriler, bütün endpointlerde sunucu tarafında concurrency limiter bulunduğu anlamına gelmez.

Bulbulustur API kimlik bilgileri mağaza hesabıyla ilişkilidir. Bu nedenle API erişiminin mağaza bağlamında değerlendirilmesi mümkündür. Kaynak kotası, bir mağazanın veya hesabın belirli bir dönem içerisinde kullanabileceği kaynak miktarını ifade eder. Gelecekte değerlendirilebilecek kota türleri: • Belirli dönemdeki veri okuma sayısı • Ürün veya varyant kayıt sayısı • Toplu işlem kapasitesi • Dosya depolama kapasitesi • Webhook yapılandırma sayısı • Rapor oluşturma ve dışa aktarma kapasitesi Bunlar olası kota kategorileridir. Bu listede yer almaları, ilgili kotaların bugün aktif olarak uygulandığı anlamına gelmez. ÖNEMLİ Bulbulustur API için aylık okuma kotası, mağaza başına ürün kotası veya genel depolama kotası gibi sayısal değerler bu dokümanda tanımlanmamıştır. Kota uygulanmaya başlandığında aşağıdaki bilgiler yayımlanmalıdır: • Kota adı • Kapsamı • Geçerli sayısal değer • Ölçüm dönemi • Kota aşımında API davranışı • Kota yenilenme koşulları Entegrasyonların, belgelenmemiş kotalara güvenerek tasarlanmaması önerilir.

Bir API isteği kullanım sınırları nedeniyle başarısız olduğunda ilk olarak HTTP durum kodunu ve yanıt içeriğini inceleyin. Farklı limit türleri farklı hata davranışlarına neden olabilir. 429 Too Many Requests: İstek hızı sınırı aşılmış olabilir. 400 Bad Request: İstek parametreleri veya gönderilen veri geçersiz olabilir. 413 Payload Too Large: İstek gövdesi izin verilen boyutu aşmış olabilir. 422 Unprocessable Content: İstek bir iş kuralı veya veri doğrulama kısıtı nedeniyle reddedilmiş olabilir. Bu kodlar genel HTTP anlamlarıyla açıklanmıştır. Bütün Bulbulustur endpointlerinin bu kodları döndürdüğü garanti edilmez. İSTEMCİ DAVRANIŞI • Hata yanıtını kontrol edin. • Sınır aşılıyorsa istek kapsamını azaltın. • Büyük istekleri daha küçük gruplara ayırın. • Desteklenen sayfalama parametrelerini kullanın. • İstek hızına bağlı sorunlarda kontrollü bekleme uygulayın. • Veri doğrulama hatalarını aynı veriyle sürekli tekrar göndermeyin. Bir kaynak sınırını aşmak ile istek hızı sınırını aşmak aynı problem değildir. Örneğin çok büyük bir JSON gövdesinin tekrar gönderilmesi, bekleme süresini artırmakla düzelmez. Hata türüne uygun çözüm uygulanmalıdır. İstek hızı sınırları ve HTTP 429 yönetimi hakkında ayrıntılı bilgi için İstek Limitleri bölümünü inceleyin.