API versiyonlama deprecation timeline'ı: 6 ay nasıl organize edilir?

Public API veya internal-but-stable API deprecate ederken düzgün timeline’ı olmadan kaos oluyor. Consumer’lar yanmaz, müşteri ticket’ları bombalanır, son anda rollback.

Son 2 yılda 3 API’nin deprecation cycle’ını yürüttüm. İyi giden, kötü giden yanları. 6 aylık process’in ideal akışı.

Neden deprecation zor

“v2’yi yayınladık, herkes v2’ye geçsin” demek işe yaramıyor. Consumer’lar:

Migration için engineering bandwidth ayırmalı
Test ortamında validate etmeli
Production’a aşamalı rollout yapmalı
Downtime riski almalı
Başka öncelikler var

Aktif v1 kullanıcısı olan bir API’yi aniden kapatamazsınız. Consumer’lar broke olur, güven kaybedersiniz.

Deprecation cycle’ı structured olmalı.

6 ay timeline’ı

Aşağıdaki timeline benim 3 deprecation deneyimimden:

T-180 gün (announcement): v2 launch ediliyor, v1 deprecation duyurusu yayınlanıyor. Migration guide hazır. Consumer’lar haberdar.

T-120 gün: response header’a deprecation warning eklenir. Analytics dashboard’da consumer bazında v1 usage görünür.

T-90 gün: major consumer’lara reach out. Migration asistansı sunulur. Progress tracking aktif.

T-60 gün: v1 endpoint’ine günlük rate limit düşürülür (warning stage). Email blast.

T-30 gün: v1 response’ında “Sunset” header’ı var. 410 Gone dönüşü plan ediliyor.

T-0 (sunset): v1 410 Gone dönüyor. Endpoint kapalı.

T+30: v1 URL route tamamen kaldırılıyor (404).

T-180: duyuru

Duyuru aynı anda şu kanallardan:

API changelog sayfası: web sitesi, RSS feed, subscribe edenler otomatik notification
Email: registered developer/consumer’lara
Developer dashboard: login yapınca banner
Blog post: detail, migration path, FAQ
Status page: upcoming deprecation sign-up

Announcement içeriği:

v1 deprecation schedule:
- Date: 2026-10-15 sunset (180 days)
- v2 available now: https://api.example.com/v2/
- Migration guide: https://docs.example.com/migrate-v1-to-v2
- What's new: [feature list]
- Breaking changes: [list with examples]
- Support: developer-support@example.com

Deadline net, migration path net, help channel net.

T-120: warning header

Her v1 response’unda HTTP header:

Deprecation: true
Sunset: Thu, 15 Oct 2026 00:00:00 GMT
Link: <https://docs.example.com/migrate-v1-to-v2>; rel="deprecation"

IETF RFC 8594 (Sunset header) standard. Modern API clients bu header’ı loglayıp dev team’e notify ediyor.

Usage tracking

Deprecation cycle’ında en kritik data: hangi consumer v1’i hala kullanıyor?

Analytics log’dan query:

SELECT 
    api_key,
    consumer_name,
    COUNT(*) as request_count,
    MAX(request_timestamp) as last_request
FROM api_log
WHERE endpoint LIKE '/v1/%'
  AND request_timestamp > NOW() - INTERVAL '7 days'
GROUP BY api_key, consumer_name
ORDER BY request_count DESC;

Top 20 consumer’a özel takip. Her birine migration asistansı.

Dashboard görselleştirme: her hafta v1 total request count ne kadar düşüyor? Graph down-right ise iyi.

T-90: proactive outreach

High-volume consumer’lara 1-on-1 iletişim:

Email: “v1 usage yüksek, yardım ister misiniz?”
Slack/Discord: technical Q&A channel
Video call: complex integration için

Ben 3 API deprecation’da high-volume consumer’larla birer kez Zoom yaptım. “Bu endpoint’i nasıl değiştireceğiz?” gibi pratik soruların anında cevabı.

Migration hızı 2x artıyor.

Breaking change catalog

Migration guide’ın kalbi: her breaking change için before/after.

### Change 1: `/v1/users/{id}` response format

Before:

json
{
“id”: 123,
“name”: “Ali”,
“email”: “ali@example.com”
}


After:

json
{
“id”: “u_abc123”, // String ID now
“profile”: {
“name”: “Ali”,
“email”: “ali@example.com”
}
}


**Migration**: 
- ID type değişimi: integer → string
- Profile field'ları nested
- Code change örneği: [migration snippet]

Her breaking change için before/after/migration. Consumer copy-paste ile kendi code’unu update edebiliyor.

T-60: rate limit reduction

60 gün kala v1 usage hala var ise rate limit’i azaltın. Aggressive signal:

Normal: 1000 req/min
T-60: 500 req/min
T-30: 100 req/min

Consumer fark ediyor, rate limit hit ediyor, migration bandwidth öncelik kazanıyor.

Bu pattern kritik consumer’ları vurmayacak care gerektiriyor. Major client’a advance warning + waive request kabul.

T-30: sunset header + last reminder

Son 30 gün:

Sunset: 2026-10-15 00:00:00 GMT header her response’ta
Final reminder email
Consumer dashboard’da countdown
“Bu tarihten sonra 410 Gone dönecek” mesajı

Consumer’lar migration veya freeze kararını vermiş olmalı bu noktada.

T-0: cutover day

Cutover feature flag ile gradual olabilir:

00:00 UTC: v1 endpoint’ten 10% traffic’e 410 Gone dön
06:00 UTC: 50% 410
12:00 UTC: 100% 410

Taşlamadan kesmek yerine batches halinde. Consumer panic hit olurken customer support arıyor.

410 Gone response:

{
    "type": "/errors/api-version-sunset",
    "title": "API Version Sunset",
    "status": 410,
    "detail": "API v1 was sunset on 2026-10-15. Please migrate to v2.",
    "migration_url": "https://docs.example.com/migrate-v1-to-v2"
}

Hata mesajında migration link. Consumer’ın panic desk’ine düşmeden çözüme yönlendirme.

T+30: route cleanup

30 gün sonra v1 route code’dan silinebilir. Artık traffic yok (410 alanlar kabul etti, 404 alacaklar zaten migrate olmuş).

Routing table temizliği, codebase küçülmesi, internal team için sadeleşme.

Consumer communication tone

Deprecation communication’ında tone önemli. Düşman değil, partner:

“v1 artık support edilmiyor” değil “v2 daha iyi, migration için size yardımcı oluyoruz”
Deadline hard ama flexibility var (kritik consumer’a 30-day extension)
Blame yok (“niye hala migrate etmediniz?” sorusu yerine “migration’da takıldığınız yer var mı?”)

Consumer’ın güveni bir deprecation ile test ediliyor, kötü handle edilirse sonraki değişikliklerde dirençli olur.

Exceptional extensions

Bazı consumer’ların geçerli sebebi olur:

“Q4 freeze var, migration Q1’de”
“Kritik integration, testing uzun sürüyor”
“Acquisition sürecindeyiz, engineering kapasite yok”

Bu case’lerde extension veriyorum. Genelde 30-60 gün ek. Ama commit ettirmek: “30 gün sonra kesinlikle migrate” + progress check-in.

Keyfi extension yok, documented reason + commitment.

Internal API deprecation

Internal API’de cycle daha kısa olabilir (3-6 hafta). Consumer aynı şirkette, communication direkt, iteration hızlı.

Yine aynı pattern:
– Announcement
– Warning header
– Usage tracking
– Outreach to high-volume consumer
– Cutover

3 hafta bile strict olmak = kaotik migration. Zaman disipline gerek.

Post-mortem

Deprecation cycle sonrası team retro:

Timeline uzun muydu / kısa mıydı?
Hangi consumer sorun yaşadı?
Hangi migration step’i unclear idi?
Next deprecation için ne değişsin?

Bu retro document’ı sonraki v3 deprecation’ına input olmalı.

Son tavsiye

API deprecation “öldür-git” süreci değil, consumer partnership. 6 ay + düzgün communication + migration asistansı.

Kısa deprecation cycle’ı (1-2 ay) = angry customer. Uzun cycle (12+ ay) = engineering debt.

6 ay sweet spot. Disciplined timeline + transparent communication ile deprecation sağlıklı yapılabiliyor.

API versiyonlama deprecation timeline’ı: 6 ay nasıl organize edilir?