Proje Önbelleği

Project Cache API, API işlemleri için projelerin bellek içi yüklenmesini yönetir. Projelerin ne zaman yüklenmesi gerektiğini anlamak, verimli API kullanımı için esastır.

Temel Kavramlar

Birleşik Önbellek Mimarisi

API ve UI aynı bellek içi önbelleği paylaşır. API üzerinden bir proje yüklendiğinde, UI tarafından kullanılan önbellek ile aynıdır. Bu şu anlamlara gelir:

• Paylaşılan Durum: API işlemleri UI kullanıcılarıyla aynı veriyi görür
• Paylaşılan Sonuçlar: Çalıştırma sonuçları API ve UI tarafından görünür
• Farklı Görünümler Yok: API ve UI'nın proje üzerinde farklı görüşleri olması imkansızdır

İşlem Kategorileri

API işlemleri önbellekleme gereksinimleri açısından üç kategoriye ayrılır:

Kategori	Açıklama	Proje Yüklemesi Gerekli mi?	Örnekler
Direct DB	Sadece okuma işlemleri	Hayır	GET uç noktaları, tenant/kullanıcı yönetimi
Auto-Load	Değişiklik işlemleri	Hayır (otomatik yükler)	Araştırmalar, not defterleri, bloklar üzerinde POST/PUT/DELETE
Requires Load	Çalıştırma işlemleri	Evet	Not defteri çalıştırma, çalıştırma sonuçlarını alma

Otomatik Yükleme Deseni (Basitleştirilmiş İş Akışı)

Çoğu CRUD işlemi için proje açıkça yüklenmesine gerek yoktur. API gerektiğinde projeyi otomatik olarak yükler:

# ESKİ iş akışı (CRUD için artık gerekmez):
# manager.load_project(project_id)  # Gerekli değil!

# YENİ iş akışı - sadece işlemi doğrudan çağırın:
response = requests.put(
    f"{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/notebook/{notebook_id}",
    json={"Name": "Updated Name"},
    headers=headers
)
# Gerekirse proje otomatik olarak yüklenir

Ne Zaman Açık Yükleme GEREKLİDİR

Projenin açıkça yüklenmesi hala çalıştırma işlemleri için zorunludur:

• POST /execution/notebook/{notebookId} - Not defterini çalıştır
• GET /execution/notebook/{notebookId}/results - Çalıştırma sonuçlarını al
• GET /execution/status/{notebookId} - Çalıştırma durumunu kontrol et

---

Projeyi Önbelleğe Yükle

GET /api/{tenantId}/project/{projectId}/load

Projeyi paylaşılan önbelleğe yükler. Not defterlerini çalıştırmadan önce kullanın.

Yol Parametreleri

Parametre	Tür	Zorunlu	Açıklama
tenantId	GUID	Evet	Tenant kimliği
projectId	GUID	Evet	Proje kimliği

Yanıt (200 OK)

{
  "projectId": "87654321-4321-4321-4321-210987654321",
  "projectName": "Purchase Order Analysis",
  "tenantName": "acme-corp",
  "investigationCount": 5,
  "notebookCount": 12,
  "datasetCount": 3,
  "loadedFromCache": false,
  "message": "Project loaded from database"
}

Yanıt Alanları

Alan	Tür	Açıklama
projectId	GUID	Proje kimliği
projectName	string	Proje adı
tenantName	string	Tenant adı
investigationCount	integer	Araştırma sayısı
notebookCount	integer	Not defteri sayısı
datasetCount	integer	Veri seti sayısı
loadedFromCache	boolean	Eğer önbellekte mevcutsa true, veritabanından yüklendiyse false
message	string	İnsan tarafından okunabilir durum mesajı

Önbellek Davranışı

Senaryo	Yanıt	Performans
İlk çağrı (önbellek yok)	loadedFromCache: false	~1000ms (veritabanı sorgusu)
Sonraki çağrılar (önbellek var)	loadedFromCache: true	~75ms (13 kat daha hızlı)
30 dk hareketsizlik sonrası	Önbellek süresi dolar	Sonraki çağrı tekrar yükler

Önbellek Özellikleri

• Süre: Son erişimden sonra 30 dakika
• Otomatik yenileme: Projeye yapılan her API çağrısı 30 dakikalık sayacı sıfırlar
• Paylaşılan: Aynı önbellek UI ve API tarafından kullanılır
• Bellek Yönetimi: %90 bellek kullanımında otomatik temizlik

---

Projeyi Önbellekten Kaldır

DELETE /api/{tenantId}/project/{projectId}/unload

Projeyi önbellekten kaldırır, belleği boşaltır.

Yol Parametreleri

Parametre	Tür	Zorunlu	Açıklama
tenantId	GUID	Evet	Tenant kimliği
projectId	GUID	Evet	Proje kimliği

Yanıt (200 OK)

{
  "projectId": "87654321-4321-4321-4321-210987654321",
  "wasInCache": true,
  "message": "Project unloaded from cache successfully"
}

---

İş Akışı Örnekleri

İş Akışı A: CRUD İşlemleri (Otomatik Yükleme)

Araştırma, not defteri veya blok oluşturma, güncelleme veya silme için:

import requests

headers = {"Authorization": f"Bearer {API_KEY}"}

# Yalnızca işlemi doğrudan çağırın - yüklemeye gerek yok!
response = requests.post(
    f"{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/investigation",
    json={"name": "New Investigation", "description": "Created via API"},
    headers=headers
)
# Gerekirse proje otomatik olarak yüklenir

İş Akışı B: Not Defteri Çalıştırma (Yükleme Gerekir)

Not defterlerini çalıştırmak ve sonuçları almak için:

import requests
import time

headers = {"Authorization": f"Bearer {API_KEY}"}

# Adım 1: Projeyi yükle (Çalıştırma için GEREKLİ)
response = requests.get(
    f"{BASE_URL}/api/{TENANT_ID}/project/{PROJECT_ID}/load",
    headers=headers
)
print(f"Proje yüklendi: {response.json()['projectName']}")

# Adım 2: Not defterini çalıştır
response = requests.post(
    f"{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/execution/notebook/{NOTEBOOK_ID}",
    headers=headers
)
print(f"Çalıştırma kuyruğa alındı: {response.json()['status']}")

# Adım 3: Tamamlanmayı kontrol et
while True:
    response = requests.get(
        f"{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/execution/status/{NOTEBOOK_ID}",
        headers=headers
    )
    status = response.json()
    print(f"Durum: {status['status']} ({status['progress']}%)")

    if status['status'] == 'Completed':
        break
    time.sleep(2)

# Adım 4: Sonuçları al
response = requests.get(
    f"{BASE_URL}/api/{TENANT_ID}/{PROJECT_ID}/execution/notebook/{NOTEBOOK_ID}/results",
    headers=headers
)
results = response.json()

# Adım 5: Projeyi önbellekten kaldır (isteğe bağlı temizlik)
requests.delete(
    f"{BASE_URL}/api/{TENANT_ID}/project/{PROJECT_ID}/unload",
    headers=headers
)

---

Uygulama Örnekleri

cURL

# Projeyi önbelleğe yükle
curl -X GET "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/project/87654321-4321-4321-4321-210987654321/load" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Projeyi önbellekten kaldır
curl -X DELETE "https://your-mindzie-instance.com/api/12345678-1234-1234-1234-123456789012/project/87654321-4321-4321-4321-210987654321/unload" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

TENANT_ID = '12345678-1234-1234-1234-123456789012'
BASE_URL = 'https://your-mindzie-instance.com'

class ProjectCacheManager:
    def __init__(self, token):
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
        self.loaded_projects = set()

    def load_project(self, project_id):
        """Projeyi önbelleğe yükle (çalıştırma işlemleri için gereklidir)."""
        url = f'{BASE_URL}/api/{TENANT_ID}/project/{project_id}/load'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()

        result = response.json()
        self.loaded_projects.add(project_id)

        status = "önbellekten" if result['loadedFromCache'] else "veritabanından"
        print(f"Proje '{result['projectName']}' {status} yüklendi")

        return result

    def unload_project(self, project_id):
        """Projeyi önbellekten kaldır."""
        url = f'{BASE_URL}/api/{TENANT_ID}/project/{project_id}/unload'
        response = requests.delete(url, headers=self.headers)
        response.raise_for_status()

        self.loaded_projects.discard(project_id)
        return response.json()

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        for project_id in list(self.loaded_projects):
            self.unload_project(project_id)

# Context manager ile kullanım
with ProjectCacheManager('your-api-key') as cache:
    result = cache.load_project('87654321-4321-4321-4321-210987654321')
    # Burada not defterlerini çalıştır...
# Çıkarken projeler otomatik kaldırılır

JavaScript/Node.js

const TENANT_ID = '12345678-1234-1234-1234-123456789012';
const BASE_URL = 'https://your-mindzie-instance.com';

class ProjectCacheManager {
  constructor(token) {
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
    this.loadedProjects = new Set();
  }

  async loadProject(projectId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/project/${projectId}/load`;
    const response = await fetch(url, { headers: this.headers });

    if (!response.ok) throw new Error(`Başarısız: ${response.status}`);

    const result = await response.json();
    this.loadedProjects.add(projectId);

    console.log(`Yüklendi: ${result.projectName} (önbellekten: ${result.loadedFromCache})`);
    return result;
  }

  async unloadProject(projectId) {
    const url = `${BASE_URL}/api/${TENANT_ID}/project/${projectId}/unload`;
    const response = await fetch(url, {
      method: 'DELETE',
      headers: this.headers
    });

    this.loadedProjects.delete(projectId);
    return response.json();
  }

  async unloadAll() {
    await Promise.all(
      Array.from(this.loadedProjects).map(id => this.unloadProject(id))
    );
  }
}

// Kullanım
const cache = new ProjectCacheManager('your-api-key');
try {
  await cache.loadProject('87654321-4321-4321-4321-210987654321');
  // Burada not defterlerini çalıştır...
} finally {
  await cache.unloadAll();
}

---

En İyi Uygulamalar

1. CRUD İşlemleri: Açıkça yükleme yapmayın - otomatik yükleme işinizi görsün
2. Çalıştırma İşlemleri: Projeyi önce mutlaka yükleyin
3. Uzun Süre Çalışan İstemciler: İşiniz bittiğinde projeleri yüklemeden kaldırın, belleği boşaltın
4. Context Manager Kullanımı: Temizlik için Python'da with, diğerlerinde try/finally kullanın
5. Bellek Bilinci: Önbellek %90 bellek kullanımında otomatik temizler; ancak açık kaldırma daha iyidir
6. Paylaşılan Önbellek: UI kullanıcılarının sizin API işlemlerinizle aynı proje durumunu gördüğünü unutmayın