Ana içeriğe geç

API sürümleme

Herkese açık API, Shopify ile aynı yaklaşımı benimseyerek tarihli sürümler kullanır; böylece geliştirme yaptığınız sürüm ayağınızın altından kaymaz. Tarihli sürümler, uyumluluğu bozan değişiklikler için kaba sınırdır; bir sürümün içinde şema yalnızca ekleme yoluyla gelişmeye devam eder.

Sürüm adları​

Bir sürümün adı YYYY-MM biçimindedir ve ay bir çeyreğin başlangıcıdır: 2026-01, 2026-04, 2026-07, 2026-10. Yeni bir tarihli sürüm yalnızca uyumluluğu bozan bir değişiklik olduğunda çıkarılır — böyle bir değişiklik içermeyen çeyrekler atlanır, dolayısıyla sürümler görece seyrektir.

Ayrıca geliştirmenin en güncel halini izleyen bir unstable sürümü de vardır; kararlı bir sürüm çıkmadan önce değişiklikleri önizlemenizi sağlar. Üretim entegrasyonlarını bunun üzerine kurmayın.

Sürüm seçme​

Öncelik sırasına göre iki yol vardır:

  1. URL yolu (önerilir): sürümü uç noktaya yazın — …/backend/<subdomain>/api/2026-07/graphql. Bu yol açıktır, önbelleğe uygundur ve kopyalanıp yapıştırılabilir.
  2. İstek başlığı: sade …/backend/<subdomain>/graphql uç noktasına X-Api-Version: 2026-07 gönderin.

Sürümü belirtmezseniz — ya da bilinmeyen veya destek süresi dolmuş bir sürüm belirtirseniz — istek, en yeni sürüm tarafından değil, hâlâ desteklenen en eski sürüm tarafından karşılanır. Uyumluluğu bozan bir değişikliğe sessizce taşınmazsınız. Sürdürmeyi düşündüğünüz her entegrasyon için sürümü açıkça sabitleyin.

Her yanıt, kendisini karşılayan sürümü X-Api-Version başlığında bildirir; böylece hangi sözleşmenin yanıt verdiğini her zaman bilirsiniz ve varsayılan davranışa güvendiyseniz sapmayı fark edersiniz.

Destek süresi​

Her kararlı sürüm en az 12 ay desteklenir ve bir sonrakiyle en az 9 ay örtüşür. Uygulamada her an iki ila üç sürüm etkindir; bu da geçiş için rahat bir zaman aralığı bırakır. Bir sürümün destek sonu tarihi, sürümün yayımlandığı gün duyurulur.

Neler uyumluluğu bozan değişiklik sayılır​

Tek bir sürümün içinde ekleme niteliğinde değişiklikler yapabiliriz ve istemcinizin bunlara dayanıklı olması gerekir:

  • yeni bir tür, sorgu veya mutasyon eklemek;
  • var olan bir alana isteğe bağlı bir argüman eklemek;
  • bir nesne türüne alan eklemek;
  • bir enum'a değer eklemek (bu nedenle bir enum'ı asla kapalı varsaymayın).

Yeni bir tarihli sürüm, gerçekten uyumluluğu bozan değişikliklere ayrılmıştır: bir alanı ya da türü kaldırmak veya yeniden adlandırmak, null kabul edilebilirliği sıkılaştırmak ya da bir argümanın veya varsayılan değerin anlamını değiştirmek. Bunlar var olan bir sürümün içinde asla gerçekleşmez — sabitlediğiniz sürüm, destek sonu tarihine kadar davranışını korur.

Kullanımdan kaldırmalar​

Kullanımdan kaldırmalar iki şekilde duyurulur; böylece bir şey bozulmadan önce haberiniz olur:

  • Şemada. Kaldırılacak bir alan @deprecated ile işaretlenir ve yerine geçecek alanı belirten bir gerekçe eklenir. İç gözlem (introspection) ve GraphQL Playground bunu her istemciye otomatik olarak gösterir.
  • Yanıtta. Bir istek gerçekten kullanımdan kaldırılmış bir alanı çözümlediğinde, yanıt X-Api-Deprecated-Reason başlığını (ve buna karşılık gelen bir extensions.deprecations girdisini) taşır ve dokunduğu belirli kullanımdan kaldırmaları adlandırır — böylece bir kullanımdan kaldırma, siz aramanıza gerek kalmadan, ona rastladığınız anda günlüklerinizde görünür.

Kullanımdan kaldırılmış bir alan, sonraki bir tarihli sürümde silinmeden önce duyurulmuş asgari bir süre boyunca korunur.