HTTP API

HTTP API to interfejs integracyjny aplikacji Beam Bench. Aplikacja desktopowa, CLI i każdy zewnętrzny klient korzystają z tych samych tras. Jeśli chcesz używać Beam Bench w środowisku innym niż CLI (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ć osobnej 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 akceptuje połączenia tylko z tego komputera.

API nie nasłuchuje połączeń, dopóki nie zostanie włączone. Włączenie dostępu sieciowego wymaga osobnej zgody, ponieważ API nie uwierzytelnia użytkowników i zawiera 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; ponowne uruchomienie nie jest wymagane.

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 IP maszyny w sieci LAN z dowolnego urządzenia w tej sieci.

Port połączenia można skonfigurować w sekcji Ustawienia → Ogólne; domyślnie jest to 5900.

Uwierzytelnianie

Brak. API nie używa tokenu, klucza ani logowania.

• Przy nasłuchiwaniu na localhost granicę dostępu 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 pliku żądania

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

Content-Type: application/json

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

Koperta odpowiedzi

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

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

Błędy zwracają jednolitą kopertę:

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

error.code ma 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 wymienioną flagą ustawioną na true. Obecnie używane flagi to confirm_motion, confirm_laser_on, confirm_raw_gcode i confirm_air_assist.

Grupy punktów końcowych

Strony informacyjne poszczególnych zasobów są w przygotowaniu; tymczasem skorzystaj ze schematu możliwości agenta.

Odkrywanie bieżącego interfejsu

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

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

Zwracany jest pełny schemat możliwości, obejmujący każdy punkt końcowy, jego parametry i format odpowiedzi. Schemat jest nadrzędnym opisem interfejsu; ta strona pełni funkcję przewodnika.

Aby sprawdzić stan:

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

Aby uzyskać pisemne wprowadzenie do sterowania aplikacją:

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

Wersjonowanie

Wszystkie trasy znajdują się pod /api/v1. W przypadku wprowadzenia zmian niezgodnych wstecznie zostanie użyte /api/v2. Zmiany przyrostowe (nowe punkty końcowe, nowe opcjonalne pola) są wdrażane w v1 bez zmiany numeru wersji.

Powiązane materiały

• Przewodnik po korzystaniu z HTTP API: wprowadzenie w formie samouczka wraz z praktycznymi przykładami.
• Jak CLI i aplikacja współdzielą stan: model spójności używany przez te punkty końcowe.
• Ustawienia → Ogólne: miejsce włączania API i wyboru portu.