Skip to Content
DokümantasyonSürümleme ve Kullanımdan Kaldırma

Sürümleme ve Kullanımdan Kaldırma

Entegrasyonunuzun bir sabah habersiz kırılmaması için sözleşmenin neyin değişebileceğini ve neyin değişemeyeceğini yazılı olarak taahhüt ediyoruz.

Ana sürüm URL’de taşınır

/api/public/v1

Ana sürüm yalnızca geriye uyumsuz bir değişiklik gerektiğinde artar. v1 ve v2 bir süre birlikte yayında kalır; hiçbir zaman bir gecede geçiş yapmanız istenmez.

Geriye uyumlu sayılan değişiklikler

Bunlar yeni ana sürüm gerektirmez; istemciniz bunlara dayanıklı olmalıdır:

  • Yanıta yeni alan eklenmesi.
  • Yeni bir endpoint veya yeni bir isteğe bağlı sorgu parametresi eklenmesi.
  • Bir enum’a yeni değer eklenmesi (ör. yeni bir alarm türü).
  • Hata mesajı metninin değişmesi — error.code değişmez, ona bakın.
  • Alanların JSON içindeki sırasının değişmesi.
İstemcinizi buna göre yazın

Bilinmeyen alanları yok sayın, bilinmeyen enum değerlerinde çökmeyin ve karar verirken hata metnine değil error.code değerine bakın. Bu üç kural entegrasyonunuzu sürüm yükseltmelerinin çoğundan korur.

Yeni ana sürüm gerektiren değişiklikler

  • Alan kaldırılması veya adının değişmesi.
  • Alan tipinin değişmesi.
  • Bir alanın isteğe bağlıyken zorunlu hale gelmesi.
  • Varsayılan davranışın değişmesi.
  • Bir endpoint’in kaldırılması.

Kullanımdan kaldırma süreci

Bir uç veya alan kaldırılacağında süreç sessiz değildir; API’nin kendisi uyarır. Kullanımdan kaldırma ilanı ile kapanma arasında en az 180 gün vardır.

İlan

Sürüm notlarına yazılır ve etkilenen uçların tüm yanıtlarına makine-okunur başlıklar eklenir.

Geçiş penceresi

En az 180 gün boyunca eski ve yeni davranış birlikte çalışır. Bu süre içinde geçişinizi yapabilirsiniz.

Kapanma

Sunset tarihinden sonra uç 410 Gone döner.

Uyarı başlıkları

Kullanımdan kaldırılmış bir uca yapılan her istek şu başlıkları döndürür:

BaşlıkAnlamı
DeprecationUcun kullanımdan kaldırıldığı tarih (RFC 9745).
SunsetUcun kapatılacağı tarih (RFC 8594).
LinkGeçiş rehberinin adresi, rel="sunset" ile.
WarningKısa, insan tarafından okunabilir açıklama.

Örnek:

HTTP/1.1 200 OK
Deprecation: Sat, 01 Aug 2026 00:00:00 GMT
Sunset: Mon, 01 Feb 2027 00:00:00 GMT
Link: <https://developer.frigolive.nl/tr/docs/versioning>; rel="sunset"
Warning: 299 - "Bu uç /shipments/{shipment_id}/tracking/ ile değiştirildi."

Uyarı başlıkları istek başarısız olsa bile döner; böylece kırılmayı loglarınızda kapanmadan önce görürsünüz.

Bunu izlemenin en kolay yolu

Backend’inizde Sunset başlığı gelen yanıtları loglayın ve bir uyarı üretin:

response = requests.get(url, headers=headers, timeout=20)
sunset = response.headers.get("Sunset")
if sunset:
    logger.warning("Frigolive ucu kapatılacak: %s -> %s", url, sunset)

Ayrıca sürüm notlarını Atom akışından takip edebilirsiniz.

Sürüm notları

Tüm sözleşme değişiklikleri Sürüm Notları sayfasında tarih sırasıyla yayınlanır.

SDK'lar ve OpenAPI