Yaşam döngüsü

API, tek ve sürekli gelişen bir GraphQL uç noktası etrafında inşa edilmiştir. Bu mimari, yeni yeteneklerin ve performans iyileştirmelerinin API sürümleri arasında geçiş yapmaya gerek kalmadan sürekli olarak sunulmasını sağlar.

Bu sayfa, API genelindeki farklı kararlılık düzeylerini, kararlı API’nin kararlılık garantilerini, değişiklik türlerini (bozucu ve bozucu olmayan) ve kullanımdan kaldırmaların nasıl yönetildiğini özetler. Şu anda önizlemede olan özellikler için deneysel özelliklere bakın.

Özellik yaşam döngüsü

Her özellik üç kararlılık düzeyinden birindedir: alpha, beta veya kararlı. Çoğu özellik bu düzeylerden sırayla geçer ve kararlı özellikler yalnızca bir kullanımdan kaldırma süreciyle sonlandırılabilir.

[ ALPHA ] ──> [ BETA ] ──> [ STABLE ] ──> [ DEPRECATED ] ──> [ REMOVED ] Opt-in        Enabled                      12+ month               by default                   notice window

Kararlı API

Kararlı işlevler, API’nin üretime hazır çekirdeğini oluşturur. Değişiklikler iki kategoriye ayrılır: bozucu olmayan ve bozucu.

Bozucu olmayan değişiklikler

Mevcut entegrasyonları aksatmayan, geriye dönük uyumlu eklemelerdir. Bunlar önceden bildirim veya kullanımdan kaldırma olmaksızın sürekli olarak yayınlanır.

Bozucu olmayan değişiklikler şunları içerir:

• Yeni bir sorgu, mutasyon veya abonelik eklemek.
• Mevcut bir işleme yeni bir isteğe bağlı girdi argümanı eklemek.
• Mevcut davranışı koruyan bir varsayılan değere sahip yeni bir argüman eklemek.
• Mevcut bir işlemin çıktısına yeni bir alan eklemek.
• Zorunlu bir girdi argümanını isteğe bağlı hale getirmek.
• Mevcut bir enum türüne yeni bir değer eklemek.

Bozucu olmayan değişiklikler için geliştirme

Bozucu olmayan değişiklikler de katı varsayımlarda bulunan istemcileri etkileyebilir. Entegrasyonları dayanıklı tutmak için:

• Yanıt gövdelerinde ek özellikler göründüğünde başarısız olan katı nesne seri durumdan çıkarmadan (deserialization) kaçının.
• GraphQL enum türleri kapsamlı değildir ve zamanla genişler. İstemci mantığında her zaman bir yedek varsayılan durum uygulayın.
• İnsan tarafından okunabilir hata metinleriyle eşleştirme yapmak yerine hataların extensions.exception.code değerlerini inceleyin.

Bozucu değişiklikler ve kullanımdan kaldırmalar

Bozucu bir değişiklik, çalışan mevcut entegrasyonları bozabilir. Bu nedenle her bozucu değişiklik önce 12 aylık bir kullanımdan kaldırma sürecinden geçmelidir.

Bozucu değişiklikler şunları içerir:

• Mevcut bir sorguyu, mutasyonu, aboneliği, alanı veya girdi argümanını kaldırmak ya da yeniden adlandırmak.
• Enum değerlerini kaldırmak ya da yeniden adlandırmak.
• Mevcut bir alanın veya girdi argümanının veri türünü değiştirmek.
• Yeni bir zorunlu girdi argümanı eklemek.
• İsteğe bağlı bir girdi argümanını zorunlu hale getirmek.
• Mevcut bir alanın iş mantığını veya davranışını değiştirmek.
• Bir çıktı alanını null olamaz (!) durumundan null olabilir duruma değiştirmek.
• Bir girdi argümanının veya alanın varsayılan değerini değiştirmek.
• Sayfalandırma varsayılanlarını, maksimum sayfa boyutlarını veya belgelenmiş sıralama düzenini değiştirmek.

Kullanımdan kaldırma zaman çizelgesi

Bozucu bir değişiklik kararlı bir yeteneğin kaldırılmasını veya değiştirilmesini gerektirdiğinde, katı bir üç aşamalı zaman çizelgesi izlenir:

1. Kullanımdan kaldırma duyurusuİşlev, GraphQL şemasında @deprecated yönergesiyle etiketlenir. Uygunsa bir geçiş yolu sağlanır. Kullanımdan kaldırma ve ilgili kaldırma tarihi, üç izleme kanalında eşzamanlı olarak duyurulur.
2. Aktif bildirim süresi (1–12. aylar)Kullanımdan kaldırılan işlev tam olarak çalışmaya devam eder. Bir geçiş yolu sağlanmışsa, entegratörler bu 12 aylık süre içinde uygulamalarını güncellemeli ve yeni alanları benimsemelidir.
3. Kalıcı kaldırmaKaldırma tarihinde işlev kalıcı olarak kaldırılır. İşlevi kullanan sonraki tüm istekler, bir GraphQL hatasıyla şema doğrulamasında başarısız olur.

Kullanımdan kaldırmaları takip etme

Yaklaşan kaldırmaları üç kanaldan belirleyin ve takip edin:

• Şema araçlarınızdaki @deprecated(reason: "...") yönergelerini inceleyin.
• Kaldırma tarihlerini ve geçiş rehberlerini API’nin eski bölümünde veya kullanımdan kaldırmalar portalında inceleyin.
• API yanıtlarında doğrudan döndürülen DEPRECATED_FEATURE uyarılarını izleyin.

{  "data": {    "station": {      "id": "5e8c22366f9c5f23ab0eff39",      "amenityList": [        {          "name": "Coffee Shop",          "foursquareUrl": "https://foursquare.com/v/example"        }      ]    }  },  "extensions": {    "warnings": [      {        "code": "DEPRECATED_FEATURE",        "path": ["amenityList", "foursquareUrl"],        "message": "This feature is deprecated and will be removed. To prevent errors and service disruptions, migrate to the recommended alternative before the scheduled removal date. Visit https://developers.chargetrip.com/deprecations for more information."      }    ]  }}