XAPI Dokümantasyonu

XAPI, dağıtık yapıda çalışan yüksek performanslı bir veri çekme (fetching) orkestrasyon motorudur. Müşterilere standartlaştırılmış veri sunarken, Node'lar ile sonsuz ölçeklenebilirlik sağlar.

Nasıl Çalışır?

Client

İsteği atar ve json bekler

Orchestrator

Yük dengeler, faturayı keser

Target Node

Görevi işler ve return eder

Müşteri API üzerinden senkron veya asenkron bir istek gönderdiğinde Orchestrator devreye girer. İstek hedefine, zorluk derecesine ve o saniye ağımızda boşta olan Node'ların durumuna bakılarak "En Yetenekli ve En Hızlı Node" anında seçilir. İstek seçilen düğüme gönderilir ve cevap müşteri için normalize edilir.

Kimlik Doğrulama

İster Müşteri olarak XAPI kullanın bağlanırken X-API-Key kullanmalısınız. Node'lar işe Authorization: Bearer kullanarak kimlik doğrular.

Müşteri İsteği Header Formatı
X-API-Key: key-SİZİN_ANAHTARINIZ
POST/api/execute/

Senkron Genel Yürütme (Client API)

Tek bir HTTP isteği ile ağı hareketlendirerek sonucu direkt yanıt olarak almanızı sağlar. Sistem arkada node seçimini, hata yönetimini ve timeout beklemesini otomatik yapar. (Maks bekleme süresi: 30 saniye)

İstek Gövdesi

type

Hedef operasyon tipi

Şu an desteklenenler: user_tweets_fetch veya search_fetch

params

Operasyon parametreleri (JSON)

Örn: {"username": "elonmusk"}

cURL İle Request Örneği
curl -X POST https://xapi.zeflexa.tr/api/execute/ \
  -H "X-API-Key: key-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user_tweets_fetch",
    "params": { 
        "username": "celalyaziyor" 
    }
  }'

Standart Normalize Yanıt

Tüm yanıtlar her zaman aynı yapıda döner. Yanıtlar normalize edildiği için Node yapısı veya farklı hedef tipleri arasında kodunuzu değiştirmeniz gerekmez.

BAŞARILI YANIT (HTTP 200)
{
  "success": true,
  "data": {
    "name": "Celal Yaziyor",
    "tweets": ["Merhabalar!", "Ölçeklenebilirlik harika."]
  },
  "meta": {
    "job_id": "job_f4d1d11cf8d9c7b6",
    "node_id": "node_l6ojwk2n",
    "duration_ms": 79,
    "token_usage": 2,
    "result_count": 2,
    "cost": 0.05,
    "cached": false
  },
  "error": null
}

Başarısız Yanıt Formatı

{
  "success": false,
  "data": null,
  "meta": { ... },
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Limit dolu"
  }
}

Hata Kodları (Error Codes)

INVALID_TYPE HTTP 400
UNAUTHORIZED HTTP 401
QUOTA_EXCEEDED HTTP 402
NO_AVAILABLE_NODE HTTP 503
NODE_TIMEOUT HTTP 504

Fiyatlandırma & Kotalar

XAPI'nin en güçlü özelliği dinamik Sonuç Hacmi Tabanlı (Result-Volume) fiyatlandırmasıdır. Sadece başarılı olan ve veri içeren sorgular için ücretlendirilirsiniz.

Hesaplama Örneği

Örneğin user_tweets_fetch için sistem size "1000 tweet sonucu başına" bir birim fiyat sunar. Hedef hesaptan 430 tweet döndüyse, maliyet tam olarak 430 tweet üzerinden hesaplanır. Eğer hesap gizliyse veya sonuç yoksa standart işlem taban (min_cost) ücreti uygulanır. Detaylı faturayı meta.cost değerinden şeffafça görebilirsiniz.

Worker / Node Kurulumu

Kendi gücünüzü XAPI ekosistemine bağlayarak işlemleri çalıştıran taraf siz olabilirsiniz!

Node Modelleri: Managed vs Remote

Managed Node (PULL)

Sunucunuz XAPI'ye belirli aralıklarla bağlanır ve "Bana iş var mı?" diye sorar. Port açmanıza veya bir API sunucusu ayağa kaldırmanıza gerek yoktur. İç ağlardaki (NAT arkası) cihazlar için mükemmeldir.

Remote Node (PUSH)

Sunucunuz kendi üzerinde HTTP/REST API barındırır. XAPI Orchestrator, iş geldiği milisaniye içinde doğrudan sizin IP'nize ve portunuza POST atar. En hızlı modeldir ancak dışarıya port açılması zorunludur.

Ağa Katılmak

Yöneticiniz panelden bir Managed Node oluşturduğunda size bir node_id vexnode_... formatında gizli bir token verilir. Tüm Node API çağrılarında bu ikisini body veya query parametresi olarak gönderirsiniz.

⚠️ Kimlik doğrulama Bearer header ile değil, her istekte node_id + token parametreleri ile yapılır.

Managed (PULL) — Tüm Endpoint'ler
POST/api/nodes/register

Node ilk açıldığında kendini sisteme kaydeder. Durumu online olur.

Kayıt İsteği
curl -X POST https://xapi.zeflexa.tr/api/nodes/register \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "node_9xzvoobh",
    "token": "xnode_GİZLİ_TOKEN",
    "base_url": "http://x1.zeflexa.tr:5000",
    "capabilities": ["username_fetch", "search_fetch"]
  }'
POST/api/nodes/heartbeat

Her 30–60 saniyede bir gönderilir. Sistemde online kalmayı sağlar.

Heartbeat İsteği
curl -X POST https://xapi.zeflexa.tr/api/nodes/heartbeat \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "node_9xzvoobh",
    "token": "xnode_GİZLİ_TOKEN",
    "healthy_accounts": 5,
    "healthy_proxies": 3,
    "active_jobs": 0,
    "avg_response_ms": 1200
  }'
GET/api/nodes/job/next

İş Çekme (Polling): Her 1–3 saniyede bir çağırırsınız. İş yoksa {"status":"no_job"} döner, iş varsa aşağıdaki gibi atanır:

cURL — İş Çekmek
curl -s "https://xapi.zeflexa.tr/api/nodes/job/next?node_id=node_9xzvoobh&token=xnode_GİZLİ_TOKEN"
Yanıt — İş Atandığında (HTTP 200)
{
  "status": "assigned",
  "job": {
    "id": "job_f4d1d11cf8d9c7b6",
    "target_username": "elonmusk",
    "job_type": "username_fetch",
    "priority": 1
  }
}
Yanıt — İş Yoksa (HTTP 200)
{
  "status": "no_job"
}
POST/api/nodes/job/{job_id}/complete

İş Raporlama: İşi bitirdiğinizde (başarılı veya hatalı) sonucu bildirirsiniz.

cURL — Başarılı İş Bildirimi
curl -X POST "https://xapi.zeflexa.tr/api/nodes/job/job_f4d1d11cf8d9c7b6/complete" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "node_9xzvoobh",
    "token": "xnode_GİZLİ_TOKEN",
    "success": true,
    "result": {
      "tweets": ["tweet1", "tweet2", "tweet3"]
    },
    "token_usage": 3,
    "error": null
  }'
cURL — Başarısız İş Bildirimi
curl -X POST "https://xapi.zeflexa.tr/api/nodes/job/job_abc123/complete" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "node_9xzvoobh",
    "token": "xnode_GİZLİ_TOKEN",
    "success": false,
    "result": null,
    "token_usage": 0,
    "error": "Account suspended or not found"
  }'
Remote (PUSH) Akışı

Remote node'lar polling yapmaz. Sunucunuz dışa açık bir HTTP portu dinler (Örn: https://sizin-sunucu.com/execute). Bir müşteri isteği geldiğinde Orchestrator doğrudan sizin sunucunuza POST atar.

Orchestrator'dan Size Gelen İstek (POST /execute)
{
  "job_id": "job_xyz987",
  "job_type": "search_fetch",
  "payload": {
    "query": "yapay zeka"
  },
  "timeout": 30
}

Görevi işledikten sonra aynı HTTP bağlantısından (Synchronous Response) şu şemayla yanıt dönmelisiniz:

Sizin Döndürmeniz Gereken Yanıt (HTTP 200)
{
  "success": true,
  "data": { "tweets": ["tweet1", "tweet2"] },
  "token_usage": 2
}