Web API Başvurusu

Temel URL

DBX Web varsayılan olarak 4224 portunu dinler:

http://localhost:4224

Bir ters proxy alt yolunun arkasında dağıtıldığında DBX_PUBLIC_BASE_PATH ayarlayın ve her rotaya önek ekleyin. Örneğin /dbx ile:

https://example.com/dbx/api/auth/check

Tüm API rotaları /api altındadır.

Kimlik Doğrulama

Korumalı rotalar dbx_session adlı bir oturum çerezi gerektirir.

Kimlik Doğrulama Durumunu Denetleme

GET /api/auth/check

Örnek yanıt:

{
  "authenticated": false,
  "required": true,
  "setup_required": false
}

İlk Çalıştırma Kurulumu

POST /api/auth/setup
Content-Type: application/json

{
  "password": "your-password"
}

Giriş

POST /api/auth/login
Content-Type: application/json

{
  "password": "your-password"
}

Başarılı olduğunda yanıt Set-Cookie: dbx_session=... başlığını ayarlar. Sonraki isteklerde bu çerezi yeniden kullanın.

Arka arkaya beş başarısız giriş, yaklaşık 60 saniyelik bir kilitlenmeyi tetikler. Oturumlar geçerli Web işleminde tutulur ve yeniden başlatmadan sonra yeniden giriş gerektirir. Çerez HttpOnly özelliklidir, SameSite=Lax kullanır ve yolu için DBX_PUBLIC_BASE_PATH değerini izler.

Çıkış

POST /api/auth/logout
Cookie: dbx_session=...

Ortam Değişkenleri

İstek Biçimi

• Alan adlandırması her Rust istek türünü izler. Bazı gövdeler camelCase kullanır, bağlantı yapılandırması ise hâlâ snake_case içerir; tek bir adlandırma kuralını API'nin tamamına uygulamayın.
• GET sorgu parametreleri genellikle connection_id gibi snake_case kullanır, ancak asıl kaynak geçerli rota uygulamasıdır.
• Hatalar genellikle bir error alanı içeren JSON ve bir HTTP durum kodu döndürür.
• Uzun süren dışa aktarma, içe aktarma, aktarım, SQL dosyası ve yapay zekâ işlemleri; tek bir eşzamanlı yanıt yerine genellikle bir başlatma isteği ile SSE ilerlemesi ve iptal/indirme rotalarını kullanır.

Şu anda yalnızca veri ızgarası çıkarıcısı, /api/query/data-grid-extractor-openapi.json adresinde test edilmiş ve kapsamı belirli bir OpenAPI belgesi sunar. Bu belge DBX Web API'sinin tamamını kapsamaz ve diğer rotaları sürümlemez.

Bağlantı API'leri

Bağlantıları Listeleme

GET /api/connection/list
Cookie: dbx_session=...

Kayıtlı bağlantı profillerini döndürür. Parolalar gibi gizli bilgiler döndürülen JSON'dan ayrı saklanır.

Bağlantıları Kaydetme

POST /api/connection/save
Content-Type: application/json
Cookie: dbx_session=...

{
  "configs": [
    {
      "name": "local-mysql",
      "db_type": "mysql",
      "host": "127.0.0.1",
      "port": 3306,
      "username": "root",
      "database": "app"
    }
  ]
}

Bağlantıyı Test Etme

POST /api/connection/test
Content-Type: application/json

{
  "config": {
    "name": "temp",
    "db_type": "mysql",
    "host": "127.0.0.1",
    "port": 3306,
    "username": "root",
    "database": "app"
  }
}

Bağlanma

Veri API'lerinin çoğu, hedef bağlantının önce etkin olmasını bekler.

POST /api/connection/connect
Content-Type: application/json

{
  "config": {
    "id": "connection-id",
    "name": "local-mysql",
    "db_type": "mysql",
    "host": "127.0.0.1",
    "port": 3306,
    "username": "root",
    "database": "app"
  }
}

Sağlığı Denetleme

POST /api/connection/check-health
Content-Type: application/json

{
  "connectionId": "connection-id"
}

Şema API'leri

Tabloları Listeleme

GET /api/schema/tables?connection_id=CONNECTION_ID&database=app&schema=
Cookie: dbx_session=...

Sütunları Listeleme

GET /api/schema/columns?connection_id=CONNECTION_ID&database=app&schema=&table=users
Cookie: dbx_session=...

Diğer şema rotaları:

• /api/schema/databases
• /api/schema/schemas
• /api/schema/indexes
• /api/schema/foreign-keys
• /api/schema/ddl

SQL Sorgu API'leri

Tek Bir İfade Çalıştırma

POST /api/query/execute
Content-Type: application/json

{
  "connectionId": "connection-id",
  "database": "app",
  "sql": "select id, name from users limit 10"
}

Örnek yanıt biçimi:

{
  "columns": ["id", "name"],
  "rows": [[1, "Ada"], [2, "Lin"]]
}

İlgili rotalar:

Redis API'leri

Redis gezgini ve komut çalıştırma kendi rotalarını kullanır.

POST /api/redis/execute-command
Content-Type: application/json

{
  "connectionId": "redis-id",
  "db": 0,
  "command": "GET mykey"
}

Diğer yaygın Redis rotaları:

• /api/redis/scan-keys
• /api/redis/get-value
• /api/redis/set-string
• /api/redis/delete-key

MongoDB API'leri

MongoDB rotaları JSON gövdeli POST uç noktalarıdır.

Koleksiyonları Listeleme

POST /api/mongo/list-collections
Content-Type: application/json

{
  "connectionId": "mongo-id",
  "database": "app"
}

Belge Bulma

POST /api/mongo/find-documents
Content-Type: application/json

{
  "connectionId": "mongo-id",
  "database": "app",
  "collection": "users",
  "skip": 0,
  "limit": 20,
  "filter": "{}"
}

Diğer MongoDB rotaları arasında aggregate-documents, insert-documents, update-documents ve delete-documents bulunur.

MCP ve CLI Tümleştirmesi

Otomasyon için bu paketleri bakımı, Web API'sini doğrudan çağırmaktan genellikle daha kolaydır:

• MCP: @dbx-app/mcp-server
• CLI: @dbx-app/cli

MCP dağıtılmış bir Web örneğine karşı çalıştığında şunu ayarlayın:

{
  "env": {
    "DBX_WEB_URL": "http://localhost:4224",
    "DBX_WEB_PASSWORD": "your-password"
  }
}

MCP sunucusu giriş ve oturum çerezlerini sizin için yönetir.

CLI aynı DBX_WEB_URL ve DBX_WEB_PASSWORD değişkenlerini destekler. İki tümleştirme de sunucu tarafındaki bağlantıları, sürücüleri, salt okunur korumayı, üretim korumasını ve veritabanı yetkilerini yeniden kullanır; bu da DBX yükseltmeleri boyunca kopyalanmış iç rota yüklerinden daha kolay bakım sağlar.

Yazmalar, Güvenlik ve Dosya Sınırları

• API kimlik doğrulaması yalnızca isteğin oturum açmış bir oturuma ait olduğunu kanıtlar; veritabanı yetkilerinin yerini almaz
• Sorgu, içe aktarma ve aktarım yolları bağlantının salt okunur korumasını uygulamayı sürdürür; üretim ve SQL risk politikası ilgili çekirdek yollarda geçerlidir
• Tarayıcıdan seçilen tablo içe aktarma ve SQL dosyaları, rastgele istemci yollarından okunmak yerine sunucudaki geçici depoya yüklenir
• Web dışa aktarımları geçici bir sunucu dosyası oluşturur, bunu bir indirme rotasıyla döndürür ve ardından temizler
• Ters proxy'ler çerezleri ve SSE akışını korumalı, uygun uzun süreli zaman aşımlarına izin vermeli ve herkese açık erişimi sınırlamalıdır

Örnek Betikler

Depodaki örneklere bakın:

• examples/web-api/automation.sh
• examples/docker/docker-compose.yml
• examples/cli/basic-workflow.sh

Rota Grupları

Web arka ucu arayüz için çok daha fazla rota sunar:

• Dışa aktarmalar ve indirmeler için /api/export/*
• Tablo içe aktarmaları için /api/import/*
• Veri aktarım işleri için /api/transfer/*
• Yerleşik yapay zekâ asistanı için /api/ai/*
• Sürücü yönetimi için /api/agents/* ve /api/jdbc/*
• Düzenleyici durumu için /api/history/* ve /api/saved-sql/*

Rotaların tam listesi için depodaki crates/dbx-web/src/main.rs dosyasına gözatın.