Sürümleme ve Hız Sınırı

Kararlılık taahhüdü, kullanımdan kaldırma başlıkları ve kota kuralları.

Kararlılık sözü

Entegrasyonunuzun bir sabah sessizce bozulmayacağını bilmelisiniz. Taahhüdümüz:

Yayınlanmış bir alanın adı ya da tipi değişmez. Değişmesi gerekiyorsa yeni sürümle gelir.
Alan eklemek kırıcı değildir. İstemciniz tanımadığı alanları yok saymalıdır — yeni alanlar eklemeye devam edeceğiz.
Enum değerleri bu sürüm için kapalı kümedir. Yeni değerler yalnız yeni bir küçük sürümle ve değişiklik kaydıyla eklenir. Tanımadığınız bir değerle (ör. bir status) karşılaşırsanız yok saymayın; güvenli bir varsayılanla ele alın ve kaydedin.
Bir uç kullanımdan kaldırılırsa Deprecation başlığı ve changelog kaydı gelir.
Kapatma tarihi en az 6 ay önceden Sunset başlığı ve changelog ile duyurulur.

Kullanımdan kaldırma başlıkları

Kullanımdan kaldırılan bir uç çalışmaya devam eder ama durumu her yanıtında söyler (örnek):

HTTP

HTTP/1.1 200 OK
Deprecation: true
Link: </api/partner/v1/ornek-yeni-uc>; rel="successor-version",
      <https://developers.supergelsin.com/surumleme>; rel="deprecation"

Kapatma tarihi belirlendiğinde Sunset başlığı eklenir. Tarih belirlenmeden bu başlık gönderilmez — uydurma bir tarih, tarih olmamasından kötüdür.

Entegrasyonunuzda Deprecation ve Sunset başlıklarını loglayın. Böylece bir uç kapanmadan aylar önce haberiniz olur; changelog'u okumayı unutsanız bile kod size söyler.

Kullanımdan kaldırılanlar

1.0.0 ilk yayındır; kullanımdan kaldırılmış bir uç yoktur.

Hız sınırı

Servis grubu ve anahtar başına 10 saniyede 50 istek. Sayım uç başına değil grup başınadır. Grupların uçları ve diğer sınırlar için Servis Limitleri sayfasına bakın.

Sipariş ve mağaza uçları katalogdan ayrı gruptadır; büyük bir katalog yüklemesi sipariş kabulünü ya da işletme kapatmayı engellemez. Bağlantı bildirimi (POST /reachability) ve kuryenin konumu da kendi gruplarında sayılır.

Kimlik doğrulamasına ulaşan her yanıt kalan bütçenizi söyler; 429 almadan görürsünüz:

HTTP

HTTP/1.1 200 OK
RateLimit-Limit: 50
RateLimit-Remaining: 47
RateLimit-Reset: 8          # pencerenin sıfırlanmasına kalan saniye

Aşımda

HTTP/1.1 429 Too Many Requests
Retry-After: 6
RateLimit-Remaining: 0

{ "error": "too_many_requests", "reason": "rate_limit", ... }

Retry-After kadar bekleyin ve üstüne biraz rastgelelik ekleyin. Aynı anda birden çok işletmeyi yoklayan bir kasa sistemi, hepsini aynı saniyeye denk getirirse kendi kendini sınıra takar.

Bütçenizi nasıl korursunuz

Menüyü If-None-Match ile yoklayın; değişmediyse gövdesiz 304 döner. 304 yanıtı da hız sınırından bir istek hakkı düşer.
Sipariş çekerken updatedSince kullanın; her seferinde tüm listeyi çekmeyin.
Güncellemeleri toplu gönderin: yemek menüsünde tek istekte 100 kalem, Çarşı katalogunda 1.000.
Webhook kurun. Anlık bildirim varken saniyede bir yoklamaya gerek kalmaz.
Çarşı senkronunda updatedSince ve imleci kullanın — tüm kataloğu her gece baştan çekmeyin.

Kararlılık sözü

Entegrasyonunuzun bir sabah sessizce bozulmayacağını bilmelisiniz. Taahhüdümüz:

Yayınlanmış bir alanın adı ya da tipi değişmez. Değişmesi gerekiyorsa yeni sürümle gelir.

Alan eklemek kırıcı değildir. İstemciniz tanımadığı alanları yok saymalıdır — yeni alanlar eklemeye devam edeceğiz.

Enum değerleri bu sürüm için kapalı kümedir. Yeni değerler yalnız yeni bir küçük sürümle ve değişiklik kaydıyla eklenir. Tanımadığınız bir değerle (ör. bir status) karşılaşırsanız yok saymayın; güvenli bir varsayılanla ele alın ve kaydedin.

Bir uç kullanımdan kaldırılırsa Deprecation başlığı ve changelog kaydı gelir.

Kapatma tarihi en az 6 ay önceden Sunset başlığı ve changelog ile duyurulur.

Kullanımdan kaldırma başlıkları

Kullanımdan kaldırılan bir uç çalışmaya devam eder ama durumu her yanıtında söyler (örnek):

HTTP

HTTP/1.1 200 OK
Deprecation: true
Link: </api/partner/v1/ornek-yeni-uc>; rel="successor-version",
      <https://developers.supergelsin.com/surumleme>; rel="deprecation"

Kapatma tarihi belirlendiğinde Sunset başlığı eklenir. Tarih belirlenmeden bu başlık gönderilmez — uydurma bir tarih, tarih olmamasından kötüdür.

Entegrasyonunuzda Deprecation ve Sunset başlıklarını loglayın. Böylece bir uç kapanmadan aylar önce haberiniz olur; changelog'u okumayı unutsanız bile kod size söyler.

Hız sınırı

Servis grubu ve anahtar başına 10 saniyede 50 istek. Sayım uç başına değil grup başınadır. Grupların uçları ve diğer sınırlar için Servis Limitleri sayfasına bakın.

Kimlik doğrulamasına ulaşan her yanıt kalan bütçenizi söyler; 429 almadan görürsünüz:

HTTP

HTTP/1.1 200 OK
RateLimit-Limit: 50
RateLimit-Remaining: 47
RateLimit-Reset: 8          # pencerenin sıfırlanmasına kalan saniye

Aşımda

HTTP/1.1 429 Too Many Requests
Retry-After: 6
RateLimit-Remaining: 0

{ "error": "too_many_requests", "reason": "rate_limit", ... }

Bütçenizi nasıl korursunuz

Menüyü If-None-Match ile yoklayın; değişmediyse gövdesiz 304 döner. 304 yanıtı da hız sınırından bir istek hakkı düşer.

Sipariş çekerken updatedSince kullanın; her seferinde tüm listeyi çekmeyin.

Güncellemeleri toplu gönderin: yemek menüsünde tek istekte 100 kalem, Çarşı katalogunda 1.000.

Webhook kurun. Anlık bildirim varken saniyede bir yoklamaya gerek kalmaz.

Çarşı senkronunda updatedSince ve imleci kullanın — tüm kataloğu her gece baştan çekmeyin.