# Sürümleme Politikası

> **Hedef Kitle:** 3. taraf entegratörler (faturalama sistemleri, özel paneller, izleme araçları).

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

| Faz | Süre | Ne olur |
|-------|----------|--------------|
| Beta | ≥ 3 ay | Endpoint'ler `/api/v2-beta/` altında mevcut; değişikliğe tabi |
| Genel sürüm | T = 0 | Endpoint'ler `/api/v2/` altında kararlı; hem v1 hem v2 erişilebilir |
| Kullanımdan kaldırma penceresi | T'den itibaren ≥ 12 ay | v1 hâlâ çalışır; her v1 yanıtında `Deprecation: true` ve `Sunset: <HTTP-date>` header'ları döner |
| Sunset | Kullanımdan kaldırma penceresinden sonra | v1 endpoint'leri `410 Gone` döner |

`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](https://semver.org/) 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
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):

```http
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`](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-generated.md), [`api-reference.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ı](sdk-php.md)) 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: `hello@wisecp.com` — Konu: `WHost API v1 compatibility regression`.