HTTP API

HTTP API, Beam Bench için entegrasyon arayüzüdür. Çoğu CLI komutu ve harici istemci bu yolları kullanır. Masaüstü ön yüzü paylaşılan hizmeti Tauri IPC üzerinden çağırır ve normal kullanım için HTTP sunucusunu gerektirmez. Beam Bench'i CLI olmayan bir ortamda, örneğin web uygulamasında, entegrasyon sunucusunda, mobil uygulamada veya kendi araçlarınızda kullanmanız gerekiyorsa API'yi doğrudan kullanın.

API masaüstü uygulamasıyla birlikte sunulur ve işlem içinde çalışır. Yüklenecek ayrı bir hizmet yoktur.

Varsayılanlar ve güvenlik

Mevcut derlemede yerel API sunucusu şu ayarlarla birlikte gelir:

• Yerel API: kapalı.
• API bağlantı noktası: 5900.
• Ağ cihazlarının bağlanmasına izin ver: kapalı. API etkinleştirildiğinde 127.0.0.1 adresine bağlanır ve yalnızca bu bilgisayardan gelen bağlantıları kabul eder.

API, siz etkinleştirmeyi seçene kadar bağlantıları dinlemez. Ağ erişimini etkinleştirmek ayrı bir açık onay gerektirir, çünkü API kimlik doğrulamasızdır ve makineyi hareket ettirebilen, lazeri çalıştırabilen işlemler içerir.

API'yi kullanmak için ayarlarını Ayarlar → Genel bölümünden değiştirin:

1. Masaüstü uygulamasını açın.
2. Düzenle → Ayarlar → Genel.
3. Yerel API seçeneğini açın.
4. Başka bir güvenilir cihazın bağlanması gerekmiyorsa Ağ cihazlarının bağlanmasına izin ver seçeneğini kapalı bırakın.

Değişiklikler hemen geçerli olur, yeniden başlatma gerekmez.

Temel URL

http://<host>:5900/api/v1

Ağ cihazlarının bağlanmasına izin ver seçeneği kapalıyken <host>, localhost veya 127.0.0.1 olur. Açıkken sunucuya ağdaki herhangi bir cihazdan makinenin LAN IP adresi üzerinden erişilebilir.

Bağlantı noktası Ayarlar → Genel bölümünden yapılandırılabilir; varsayılan değer 5900'dür.

Kimlik doğrulama

Yok. API'de belirteç, anahtar veya oturum açma yoktur.

• localhost bağlamasında sınır, işletim sistemi düzeyindeki erişim modelidir: makinenizdeki her işlem API ile iletişim kurabilir.
• Ağ bağlaması etkinleştirildiğinde aynı ağdaki herkes API ile iletişim kurabilir. Ağ bağlama modunu güvenilmeyen Wi-Fi üzerinde kullanmayın.

İstek biçimi

Tüm POST/PATCH/PUT gövdeleri JSON'dur:

Content-Type: application/json

Sorgu dizeleri düz key=value biçimindedir. Yol bölümleri her zamanki gibi URL kodlamalıdır.

Yanıt kapsayıcısı

Başarılı yanıtlar kaynağın gövdesini doğrudan, sarmalayıcı olmadan döndürür:

{
  "field": "value",
  "...": "..."
}

Hatalar tek tip bir kapsayıcı döndürür:

{
  "error": {
    "code": "invalid_input",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

error.code değerlerinden biri şudur:

Onay gerektiren hatalar

Makineyi hareket ettirebilen veya lazeri çalıştırabilen az sayıda işlem vardır. Bu uç noktalar, istek gövdesinde açık bir onay işareti gerektirir. İşaret eksikse API 428 Precondition Required döndürür:

{
  "error_code": "CONFIRMATION_REQUIRED",
  "missing": ["confirm_motion"],
  "message": "This command can move the machine and requires explicit confirmation."
}

İsteği, adı belirtilen işareti true olarak ayarlayarak yeniden gönderin. Şu anda kullanılan işaretler confirm_motion, confirm_laser_on, confirm_raw_gcode ve confirm_air_assist değerleridir.

Eş zamanlı proje düzenlemeleri

Tasarım işlemleri, yakalanan projeyi gönderme zamanında karşılaştırır. Eş zamanlı bir düzenleme, proje değişikliği veya kapatma stale_revision döndürebilir. Yeniden denemeden önce durumu yenileyin ve değişikliği yeniden değerlendirin. Eski bir proje anlık görüntüsünü yeni çalışmanın üzerine düşünmeden yeniden uygulamayın.

Uç nokta grupları

Kaynak başına referans sayfaları hazırlanmaktadır; bu sırada agent yetenek şemasına bakın.

Canlı arayüzü keşfetme

Yüklü sürümünüzün sunduklarını görmenin en hızlı yolu:

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

Bu komut, her uç noktayı, parametrelerini ve yanıt biçimini içeren tam yetenek şemasını döndürür. Şema yetkili açıklamadır; bu sayfa ise ona yönelik bir kılavuzdur.

Durum incelemesi için:

curl -s http://localhost:5900/api/v1/agent/state | jq .

Uygulamanın nasıl yönetileceğine dair yazılı bir yönlendirme için:

curl -s http://localhost:5900/api/v1/agent/guide

Sürüm oluşturma

Tüm yollar /api/v1 altındadır. Kırıcı değişiklikler gerçekleştiğinde /api/v2 içine alınır. Eklemeli değişiklikler, yeni uç noktalar ve yeni isteğe bağlı alanlar gibi, sürüm artırılmadan v1 içinde sunulur.

İlgili

• HTTP API'yi kullanma kılavuzu: çalışan örneklerle öğretici bir giriş.
• CLI ve uygulamanın durumu nasıl paylaştığı: bu uç noktaların arkasındaki tutarlılık modeli.
• Ayarlar → Genel: API'nin etkinleştirileceği ve bağlantı noktasının seçileceği yer.