HTTP API

HTTP API, Beam Bench için entegrasyon arayüzüdür. Masaüstü uygulaması, CLI ve tüm harici istemciler aynı uç noktalarla iletişim kurar. Beam Bench'i CLI dışı bir ortamda kullanmanız gerekiyorsa (web uygulaması, entegrasyon sunucusu, mobil uygulama veya kendi araçlarınız), API'yi doğrudan kullanın.

API, masaüstü uygulamasıyla birlikte gelir ve uygulama 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ı olmadan çalışır ve makineyi hareket ettirebilen ve 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 kapalı olduğunda <host>, localhost (veya 127.0.0.1) olur. Bu seçenek açık olduğunda 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ğlantısında sınır, işletim sistemi düzeyindeki erişim modelidir: makinenizdeki herhangi bir işlem API ile iletişim kurabilir.
• Ağ bağlantısı etkinleştirildiğinde aynı ağdaki herkes API ile iletişim kurabilir. Güvenilmeyen Wi-Fi ağlarında ağ bağlantısı modunu 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 kodlamasıyla belirtilir.

Yanıt kapsayıcısı

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

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

Hatalar standart bir kapsayıcı döndürür:

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

error.code değerlerinden biri şunlardır:

Onay gerektiren hatalar

Az sayıda işlem makineyi hareket ettirebilir veya lazeri çalıştırabilir. Bu uç noktalar, istek gövdesinde açık bir onay bayrağı gerektirir. Bayrak 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."
}

Adı belirtilen bayrağı true olarak ayarlayarak isteği yeniden gönderin. Şu anda kullanılan bayraklar confirm_motion, confirm_laser_on, confirm_raw_gcode ve confirm_air_assist değerleridir.

Uç nokta grupları

Kaynak başına referans sayfaları hazırlanmaktadır, bu sırada ajan yetenek şemasına başvurun.

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ç noktanın parametreleri ve yanıt biçimi dahil olmak üzere tüm yetenek şemasını döndürür. Şema yetkili açıklamadır, bu sayfa ise şemaya yönelik bir kılavuzdur.

Durum inceleme için:

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

Uygulamanın nasıl yönlendirileceğine dair yazılı bir genel bakış için:

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

Sürüm oluşturma

Tüm yollar /api/v1 altında bulunur. Geride uyumsuz değişiklikler yapıldığında /api/v2 altında sunulur. Eklemeli değişiklikler (yeni uç noktalar, yeni isteğe bağlı alanlar) sürüm numarası artırılmadan v1 içinde sunulur.

İlgili

• HTTP API kılavuzunu kullanma: örneklerle anlatılan öğretici bir giriş.
• CLI ve uygulama durumu nasıl paylaşır: 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 bölüm.