HTTP API

HTTP API jest interfejsem integracyjnym Beam Bench. Większość poleceń CLI i klientów zewnętrznych korzysta z tych tras. Frontend desktopowy wywołuje wspólną usługę przez Tauri IPC i podczas normalnego użycia nie wymaga serwera HTTP. Jeśli potrzebujesz używać Beam Bench w środowisku innym niż CLI, na przykład w aplikacji internetowej, serwerze integracyjnym, aplikacji mobilnej lub własnych narzędziach, użyj bezpośrednio API.

API jest dostarczane z aplikacją desktopową i działa w tym samym procesie. Nie trzeba instalować oddzielnej usługi.

Ustawienia domyślne i bezpieczeństwo

W bieżącej wersji lokalny serwer API korzysta z następujących ustawień:

• Lokalne API: wyłączone.
• Port API: 5900.
• Zezwól urządzeniom w sieci: wyłączone. Gdy API jest włączone, nasłuchuje na 127.0.0.1 i przyjmuje połączenia tylko z tego komputera.

API nie nasłuchuje połączeń, dopóki nie wyrazisz na to zgody. Włączenie dostępu sieciowego wymaga osobnej zgody, ponieważ API nie ma uwierzytelniania i obejmuje operacje, które mogą poruszać maszyną oraz uruchamiać laser.

Aby używać API, zmień jego ustawienia w sekcji Ustawienia → Ogólne:

1. Otwórz aplikację desktopową.
2. Edycja → Ustawienia → Ogólne.
3. Włącz Lokalne API.
4. Pozostaw opcję Zezwól urządzeniom w sieci wyłączoną, chyba że inne zaufane urządzenie musi się połączyć.

Zmiany zaczynają obowiązywać natychmiast, bez ponownego uruchamiania.

Bazowy adres URL

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

<host> to localhost lub 127.0.0.1, gdy opcja Zezwól urządzeniom w sieci jest wyłączona. Gdy jest włączona, serwer jest dostępny pod adresem LAN maszyny z dowolnego urządzenia w sieci.

Port można skonfigurować w sekcji Ustawienia → Ogólne; 5900 to wartość domyślna.

Uwierzytelnianie

Brak. API nie ma tokenu, klucza ani logowania.

• Przy nasłuchiwaniu na localhost granicę stanowi model dostępu na poziomie systemu operacyjnego: każdy proces na komputerze może komunikować się z API.
• Przy włączonym nasłuchiwaniu sieciowym każdy użytkownik tej samej sieci może komunikować się z API. Nie używaj trybu nasłuchiwania sieciowego w niezaufanych sieciach Wi-Fi.

Format żądania

Wszystkie treści żądań POST/PATCH/PUT są zapisane jako JSON:

Content-Type: application/json

Parametry zapytań mają płaską postać key=value. Segmenty ścieżki są kodowane w adresie URL w zwykły sposób.

Koperta odpowiedzi

Pomyślne odpowiedzi zwracają bezpośrednio treść zasobu, bez opakowania:

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

Błędy zwracają jednolitą kopertę:

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

error.code przyjmuje jedną z wartości:

Błędy wymagające potwierdzenia

Niewielka grupa operacji może poruszać maszyną lub uruchamiać laser. Te punkty końcowe wymagają jawnej flagi potwierdzenia w treści żądania. Jeśli jej brakuje, API zwraca 428 Precondition Required:

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

Wyślij żądanie ponownie z nazwaną flagą ustawioną na true. Obecnie używane flagi to confirm_motion, confirm_laser_on, confirm_raw_gcode i confirm_air_assist.

Jednoczesne edycje projektu

Transakcje projektowe porównują przechwycony projekt podczas zatwierdzania. Jednoczesna edycja, zmiana projektu lub jego zamknięcie może zwrócić stale_revision. Odśwież stan i ponownie oceń zmianę przed ponowieniem próby. Nie odtwarzaj bezmyślnie starszej migawki projektu na nowszej pracy.

Grupy punktów końcowych

Strony referencyjne poszczególnych zasobów są nadal tworzone. W międzyczasie zapoznaj się ze schematem możliwości agenta.

Odkrywanie bieżącego interfejsu

Najszybszy sposób na sprawdzenie, co udostępnia zainstalowana wersja:

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

Zwraca to pełny schemat możliwości, obejmujący każdy punkt końcowy, jego parametry i kształt odpowiedzi. Schemat jest autorytatywnym opisem, a ta strona stanowi przewodnik po nim.

Aby sprawdzić stan:

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

Aby uzyskać opisowy przewodnik dotyczący obsługi aplikacji:

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

Wersjonowanie

Wszystkie trasy znajdują się pod /api/v1. Zmiany powodujące niezgodność trafiają do /api/v2, gdy się pojawiają. Zmiany przyrostowe, takie jak nowe punkty końcowe i nowe opcjonalne pola, są wprowadzane w v1 bez zmiany wersji.

Powiązane

• Przewodnik po używaniu HTTP API: wprowadzenie w formie samouczka z przykładami.
• Jak CLI i aplikacja współdzielą stan: model spójności stojący za tymi punktami końcowymi.
• Ustawienia → Ogólne: miejsce włączania API i wyboru portu.