Sürümleme Politikası

WHost API kararlılık taahhütleri aşağıda kodlanmıştır. Bu belge yetkili referanstır — uygulama davranışı burada yazılana uyar, tersi değil.

1. Sürüm Öneki

Her endpoint /api/vN/ altına bağlanır; burada N ana (major) sürümdür. Bugün yalnızca v1 mevcuttur. Sürüm öneki olmadan bir path'e yapılan istek istemci tarafı bir hatadır ve 404 döner. (Şema ayrıca agent'ın yerel canlılık yoklaması /health'i listeler; agent'ın önündeki web sunucusu onu yayımlamaz.)

GET /api/v1/accounts/{username}        ✔ kanonik
GET /accounts/{username}                ✘ 404

2. v1 Kararlılığı

v1 sonsuza kadar kararlıdır. Bir v1 endpoint'i, istek alanı veya yanıt alanı bir sürümde yayınlandığında, v1'in ömrü boyunca kalıcıdır.

v1'de izin verilenler:

• Yeni endpoint ekleme (additive)
• Yeni opsiyonel istek alanları ekleme
• Yanıt payload'larına yeni alanlar ekleme (istemciler bilinmeyen alanları yok saymalıdır)
• Belgelenmiş sözleşmeye davranışı uyumlu hale getiren hata düzeltmeleri

v1'de izin verilmeyenler:

• Bir endpoint'i kaldırma
• Bir istek/yanıt alanını kaldırma veya yeniden adlandırma
• Bir alanın tipini değiştirme
• Doğrulamayı sıkılaştırma (daha önce kabul edilen girdileri reddetme)
• Belgelenmiş bir başarı durumunun döndürdüğü HTTP durum kodunu değiştirme

Yukarıdakilerden biri zorunlu hale gelirse, v1 değişikliği olarak değil v2 olarak yayınlanır.

3. Ana Sürüm Atlamaları (v2, v3, …)

Yeni bir ana sürüm, paralel bir path öneki olarak tanıtılır (/api/v2/). Agent her iki sürümü tüm kullanımdan kaldırma penceresi boyunca yan yana sunar — hiçbir istemci bir sürümde geçişe zorlanmaz.

Duyurulmuş bir v2 yoktur ve v1'de kullanımdan kaldırılmış hiçbir şey yoktur: aşağıdaki fazlar yeni bir ana sürüm duyurulduğunda olacakları anlatır.

Duyuru takvimi

v2'yi duyurmak ile v1'i kaldırmak arasındaki minimum pencere 15 aydır (3 ay beta + 12 ay kullanımdan kaldırma).

4. Minor ve Patch Sürümleri

Agent'ın __version__ değeri (örn. 1.0.0-beta.1, 1.0.0) Semantic Versioning standardını takip eder. Herkese açık sürüm hattı 1.0.0-beta.1'den başlar; ondan önceki build'ler hiç yayımlanmamış iç numaralar taşıyordu. Ön sürüm etiketi paketlenen sürümün kendisindedir (1.0.0-beta.1): beta'daki bir kurulum, olgunlaşacağı sürümün altında sıralanır ve o sürüm ona sunulur; güncelleme paketi, installer'ın WHOST_VERSION değeri ve panelin package.json dosyası aynı dizeyi taşır. WHost'un yayımlandığı tek ön sürüm türü beta'dır (1.0.0-beta.9 < 1.0.0-beta.10 < 1.0.0).

• Patch (z) — yalnızca hata düzeltmeleri; API yüzeyinde değişiklik yok.
• Minor (y) — mevcut ana sürüm içinde additive API değişiklikleri (yeni endpoint, yeni opsiyonel alan, yeni yanıt alanı).
• Major (x) — yeni bir /api/vN/ öneki getirebilecek tek sürüm türü; eski önek §3'e göre korunur.

Sürüm numarası ile API öneki ayrı sayılır: 1.x agent v1'i sunar. Bir hattın betaları (1.0.0-beta.N) tek bir sürümün ön izlemeleridir ve hem düzeltme hem ekleme taşıyabilir; yukarıdaki türler sürümler arasındaki adımları anlatır.

5. Kullanımdan Kaldırma Header'ları

Bugün hiçbir yanıt bu header'ları taşımaz: v1'de kullanımdan kaldırılmış hiçbir şey yoktur. v1 kullanımdan kaldırma penceresine girdiğinde her v1 yanıtı bunları taşıyacaktır (aşağıdaki tarih örnektir; bir sunset tarihi belirlenmemiştir):

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Tue, 30 Sep 2027 00:00:00 GMT
Link: </api/v2/accounts/{username}>; rel="successor-version"

Link header'ı, varsa eşdeğer v2 endpoint'ine işaret edecektir.

Bir ana sürüm içindeki bireysel endpoint'ler de tam bir sürüm atlaması olmadan kullanımdan kaldırılabilir. Bu durumda aynı Deprecation / Sunset header'ları yalnızca o endpoint'te gönderilecek; sürümün geri kalanı uyarısız kalacaktır.

6. Ana Sürüm İçinde Alan Düzeyinde Kaldırma

Bir alan, ana sürüm içinde kullanımdan kaldırılmış olarak işaretlenebilir (hâlâ döner, ancak işaretlenmiştir). Bugün kullanımdan kaldırılmış bir alan yoktur; olduğunda agent şuna benzer bir uyarı gönderecektir (alan adları örnektir):

Warning: 299 - "Field 'legacy_quota_bytes' is deprecated; use 'quota_bytes' instead"

Alan, §3 kullanımdan kaldırma penceresinin tamamı boyunca doldurulmaya devam eder; ardından null olur ve nihayetinde bir sonraki ana sürümde kaldırılır.

7. Kırıcı Hata Düzeltmesi İstisnası

Belgelenmiş bir v1 davranışının güvensiz olduğu tespit edilirse (örn. belirli bir kod yolunda eksik bir yetkilendirme kontrolü), düzeltme gözlemlenebilir davranışı değiştirse bile bir v1 patch'i olarak yayınlanır. Bu tür düzeltmeler:

• Sürüm notlarında Security başlığı altında listelenir
• Operasyonel olarak mümkün olduğunda sürümden 7 gün önce duyurulur
• Etkilenen entegratörler için bir geçici çözüm ile birlikte sunulur

Bu istisna yalnızca bir güvenlik veya veri bütünlüğü riskini kapatan düzeltmeler için geçerlidir. Saf UX tercihleri bu kapsama girmez.

8. OpenAPI Şeması Tek Doğruluk Kaynağı

GET /api/v1/openapi.json adresindeki OpenAPI 3.1 şeması (imzalı istek ya da yönetici oturumu; anonim erişim yoktur), v1'in kanonik makine tanımıdır; bir kopyası bu belgenin yanında openapi.json olarak yayımlanır. Bu belge ile şema arasında bir uyuşmazlık varsa, şema kazanır — bunu §10'da anlatıldığı gibi bildirin. Endpoint başına referans (api-reference-generated.md, api-reference.md üzerinden ulaşılır) şemadan üretilir.

9. SDK Uyumluluk Taahhüdü

Bugün tek resmi SDK PHP SDK'dır; bu siteden indirilir (bkz. PHP SDK sayfası) ve v1 API'sini hedefler. Sürüm numarası kendisine aittir: 0.x olduğu sürece (bugün 0.1.1) bir ara sürüm davranış değiştirebilir ve bunu CHANGELOG.md söyler. 1.0.0'dan itibaren bir SDK ana sürümü bir API ana sürümünü hedefler: 1.x.y, v1'e karşı çalışır; bir v2 API yayınlanırsa yeni bir SDK ana sürümü gelir ve 1.x hattı v1 kullanımdan kaldırma penceresi boyunca düzeltme almaya devam eder. Python ve Node.js SDK'ları planlandı, yayımlanmadı.

10. Uyumluluk Sorunu Nasıl Bildirilir

v1'e entegre ettiyseniz ve bir agent sürümü entegrasyonunuzu bozarsa, bu WHost'ta bir hatadır — sizin kodunuzda değil. Aşağıdakileri içeren bir ticket açın:

1. Agent sürümü (GET /api/v1/system/update/status → current_version)
2. Daha önce çalışan endpoint + istek gövdesi
3. Gözlemlenen yanıt (durum kodu + gövde)
4. Beklenen yanıt

İletişim: [email protected] — Konu: WHost API v1 compatibility regression.