API sürümleme ve kullanımdan kaldırma

REST API, ana sürümünü yolda taşır: /api/v1. Bir ana sürüm içinde API yalnızca mevcut istemcilerin çalışmaya devam ettiği şekillerde değişir. Bir istemciyi bozabilecek bir değişiklik, yürürlüğe girmesinden en az 6 ay önce duyurulur: API referansında, API değişiklik günlüğünde ve etkilenen işlemin her yanıtının başlıklarında.

Bu politika 2026-10-18 tarihinden itibaren geçerlidir. Genel kullanıma sunulmadan önce yapılan değişiklikler bildirim süresine tabi değildi. Bu değişiklikler API değişiklik günlüğünde listelenir.

Yoldaki sürümBağlantıyı kopyalayın

https://<api-host>/api/v1

• <api-host>: API’nin ana bilgisayar adı.

Yeni bir ana sürüm, v1 ile yan yana, /api/v2 gibi kendi yolunda sunulur. v1 kullanılabilir kalır ve v1 üzerinde uyumluluğu bozan bir değişiklik yine en az 6 ay önceden bildirim gerektirir.

Geriye dönük uyumlu değişikliklerBağlantıyı kopyalayın

Bu değişiklikler v1 içinde her zaman yapılabilir. İstemcinizi, bu değişiklikler olduğunda da çalışmaya devam edecek şekilde oluşturun:

Uyumluluğu bozan değişikliklerBağlantıyı kopyalayın

Bu değişiklikler, aşağıdaki kullanımdan kaldırma süreci izlenmeden bir işleme hiçbir zaman uygulanmaz:

• Bir işlemi veya yolu kaldırmak.
• Zorunlu bir parametre veya zorunlu bir istek alanı eklemek ya da isteğe bağlı bir parametreyi veya alanı zorunlu yapmak.
• Bir alanın veya parametrenin türünü değiştirmek.
• Bir istek enum’undan bir değeri kaldırmak ya da daha kısa bir azami uzunluk, daha küçük bir azami değer, daha az öğe veya yeni bir desen gibi doğrulamayı sıkılaştırmak.
• Bir yanıt alanını kaldırmak ya da isteğe bağlı veya null olabilir yapmak.
• Bir başarı durum kodunu veya bir medya türünü kaldırmak.
• İşlemin önceden gerektirmediği bir belirteç kapsamını gerektirmek ya da herhangi birinin yettiği bir kapsam kümesinden kapsam çıkarmak.
• API belirteçlerini ve servis hesabı anahtarlarını kabul eden bir işlemde bunları reddederek işlemi yalnızca bir konsol oturumunda çalışır hâle getirmek.

Uyumluluğu bozan bir değişiklik nasıl duyurulurBağlantıyı kopyalayın

Uyumluluğu bozan bir değişiklik yürürlüğe girmeden en az 6 ay önce:

• İşlem, API referansında ve https://<api-host>/openapi.json adresindeki OpenAPI belgesinde kullanımdan kaldırılmış olarak işaretlenir. İşlemde deprecated: true, duyuru tarihi olan x-deprecation-date ve işlemin çalışmayı bırakabileceği en erken tarih olan x-sunset bulunur. Her iki tarih de RFC 3339 biçimindedir.
• API değişiklik günlüğündeki bir kayıt, değişikliği ve bunun yerine ne kullanılacağını açıklar.
• İşlemin her yanıtı, aşağıdaki tablodaki başlıkları taşır.

Deprecation: @1792281600
Sunset: Sun, 18 Apr 2027 00:00:00 GMT
Link: <https://docs.cloud.example/docs/developers/rest-api/changelog/>; rel="deprecation"; type="text/html"

Bu örnekte işlem 2026-10-18 tarihinde kullanımdan kaldırıldı ve 2027-04-18 tarihinden sonra çalışmayı bırakabilir.

Başlıklar, 401, 403 ve 429 gibi hata yanıtları da dahil olmak üzere işlemin her yanıtında bulunur. Kullanımdan kaldırmayı yanıtların kendisinden öğrenmek için istemcinizde Deprecation başlığını günlüğe kaydedin veya bu başlık için bir uyarı oluşturun.

Son kullanma tarihinden sonraBağlantıyı kopyalayın

Sunset içindeki tarihe kadar, kullanımdan kaldırılmış bir işlem belgelendiği gibi çalışmaya devam eder. Bu tarihten sonra işlem kaldırılabilir veya değiştirilebilir. Değişiklik günlüğündeki kayıt, bunun yerine ne kullanılacağını belirtir.

Politika nasıl denetlenirBağlantıyı kopyalayın

Herkese açık API sözleşmesindeki her değişiklik, kendisinden önce yayımlanan sözleşmeyle otomatik olarak karşılaştırılır. Uyumluluğu bozan bir fark, değişikliğin yayımlanmasını durdurur. Tek istisna, kullanımdan kaldırılmış ve son kullanma tarihi geçmiş bir işlemdir.

İlgili içerikBağlantıyı kopyalayın

• API değişiklik günlüğü
• REST API’ye genel bakış
• Hatalar
• API referansı