10 — Uygulama Yönetim API'si (M2M)

Kimin için: Uygulama sunucularını TALOST ID ile otomatik yönetmek, sağlık izlemek ve feature flag sorgulamak isteyen geliştiriciler.
Ön koşul: Geliştirici Portalından alınmış bir App API Key (tlk_live_... veya tlk_test_...).
Tahmini süre: 15 dakika.

Ne Öğreneceksiniz

• Makineden makineye (M2M) App API Key kimlik doğrulamasını,
• Periyodik sağlık sinyali (Heartbeat) göndermeyi ve canlı durumu raporlamayı,
• Uzaktan Konfigürasyon (ETag ile 304 önbellek) ve Feature Flag motorunu kullanmayı,
• İstemciler için Sürüm Kontrolü (version-check) yapmayı.

Kimlik Doğrulama ve Güvenlik

Tüm /api/v1/apps/** uç noktaları AppApiKey ile korunur:

• Header: X-Talost-Api-Key: tlk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  (veya Authorization: Bearer tlk_live_...)
• Hız Sınırı (Rate Limit): API anahtarı başına dakikada 600 istek.
• Ortam Etiketi: Yanıt başlıklarında X-Talost-Environment: PRODUCTION (veya DEVELOPMENT) bilgisi iletilir.

Uç Noktalar ve Kullanım

1. Kimlik ve Yetki Kontrolü (`GET /api/v1/apps/me`)

API anahtarınızın geçerli olup olmadığını ve bağlı olduğu uygulama detaylarını döner.

• Gerekli Scope: heartbeat

curl -H "X-Talost-Api-Key: tlk_live_..." https://id.talost.com/api/v1/apps/me

2. Sağlık Sinyali Gönderme (`POST /api/v1/apps/heartbeat`)

Uygulama sunucunuzun veya mikroservisinizin ayakta olduğunu TALOST ID'ye bildirir. Panelde yeşil durum ışığı yanması için periyodik (örneğin 60 saniyede bir) çağrılmalıdır.

• Gerekli Scope: heartbeat
• Gövde:

{
  "platform": "WEB",
  "version": "1.4.2",
  "instance_id": "srv-prod-node-01",
  "status": "OK",
  "details": {
    "memory_mb": 420,
    "uptime_seconds": 86400
  }
}

• Yanıt: { "ok": true, "next_in_seconds": 60 }

3. Uygulama ve Ekosistem Durumu (`GET /api/v1/apps/status`)

Uygulamanın aktif bakımda olup olmadığını, global duyuruları ve platform bazlı son sürüm bilgilerini döner.

• Gerekli Scope: heartbeat
• Yanıt:

{
  "app_status": "ACTIVE",
  "maintenance": {
    "active": false,
    "message": null,
    "ends_at": null
  },
  "announcements": [],
  "versions": {
    "WEB": {
      "latest_version": "1.4.2",
      "min_supported_version": "1.0.0",
      "forced_update": false,
      "download_url": null
    }
  }
}

4. Uzaktan Konfigürasyon (`GET /api/v1/apps/config`)

Uygulamanızı yeniden derlemeden veya deploy etmeden panelden ortam bazlı parametreleri güncellemenizi sağlar. ETag başlığını destekler; içerik değişmediğinde 304 Not Modified döner ve bant genişliğini korur.

• Gerekli Scope: config.read

# İlk İstek:
curl -i -H "X-Talost-Api-Key: tlk_live_..." https://id.talost.com/api/v1/apps/config
# ETag: "a1b2c3d4..." döner

# Sonraki İstek (Önbellek Kontrolü):
curl -i -H "X-Talost-Api-Key: tlk_live_..." -H 'If-None-Match: "a1b2c3d4..."' https://id.talost.com/api/v1/apps/config
# HTTP 304 Not Modified döner

5. Feature Flag Değerlendirme (`GET /api/v1/apps/flags/evaluate?user_id=...`)

Kullanıcı bazlı, plan bazlı veya yüzde dağılımlı (kademeli geçiş) bayrakları kullanıcı için değerlendirir.

• Gerekli Scope: config.read
• Yanıt:

{
  "flags": {
    "new_dashboard_v2": true,
    "beta_export_excel": false
  }
}

6. İstemci Sürüm Denetimi (`GET /api/v1/apps/version-check`)

Mobil veya masaüstü uygulamalar açılışta zorunlu güncelleme kontrolü yapmak için bu ucu anonim olarak çağırabilir.

• Kimlik Doğrulama: Yok (Genel Uç Nokta)
• Hız Sınırı: IP başına dakikada 60 istek.
• İstek: GET /api/v1/apps/version-check?client_id=cli_...&platform=WINDOWS&version=1.2.0
• Yanıt:

{
  "latest_version": "2.0.0",
  "min_supported_version": "1.5.0",
  "update_available": true,
  "forced_update": true,
  "download_url": "https://download.example.com/setup-2.0.0.exe"
}

Kod Örneği: Node.js Heartbeat Ajanı

Uygulamanız başlarken arka planda periyodik heartbeat gönderen hafif servis:

// heartbeat.ts
export function startHeartbeatAgent() {
  const apiKey = process.env.TALOST_APP_API_KEY;
  const issuer = process.env.TALOST_ISSUER || "https://id.talost.com";
  if (!apiKey) return;

  async function ping() {
    try {
      await fetch(`${issuer}/api/v1/apps/heartbeat`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Talost-Api-Key": apiKey,
        },
        body: JSON.stringify({
          platform: "WEB",
          version: process.env.npm_package_version || "1.0.0",
          instance_id: process.env.HOSTNAME || "node-instance",
          status: "OK",
        }),
      });
    } catch (err) {
      console.warn("TALOST ID heartbeat gönderilemedi:", err);
    }
  }

  // İlk ping hemen, ardından her 60 saniyede bir
  ping();
  setInterval(ping, 60000);
}

Güvenlik Notları

• AppApiKey anahtarını kesinlikle istemci taraflı tarayıcı veya mobil kodlara koymayın.
• API anahtarı gizli bir sistem anahtarıdır; sadece kendi sunucunuzdan (Back-end) TALOST ID'ye yapılan çağrılarda kullanılmalıdır.

İlgili Sayfalar

• 07. Lisans ve Entitlement Kontrolü
• 11. Bakım Modu ve Duyurular
• 18. @talost/app-sdk Kullanımı

Son doğrulama: 2026-10-04 · Kaynak: _envanter.md, src/lib/apps/api-key.ts, src/app/api/v1/apps/**