5.2 Linking with Control Programs (WebAPI)

5.2.1 Introduction to WebAPI#

Some operations in SpeeDBee Synapse can be performed the outside through the API.

5.2.2 How to run the WebAPI#

As an example, the method to execute the API using the curl command is shown here.
If you don't have curl installed, download it from the official curl site and install it on your machine.

Open the environment in which you want to run the curl command. Open Terminal in the case of Linux and open Command Prompt in the case of Windows.
Copy the “Request with curl Command” for each API in the API Specification and paste it into the environment where you want to run the curl command.
Note: Some of the “requests by curl command” need be replaced. For more information, see “Common Issues”.
Press Enter to run the API and the response is displayed. For details about the response, see "Response" of each API in "API specification."

The curl command requests for each API in the “API Specification” specify the following: If you use a method other than the curl command to execute the API, you must specify the same items.

Item	Description
The specification is shown in the form of	HTTP method
This is the URL starting from	Request URL
The specification is shown in the form of	HTTP header
The specification is shown in the form of	Data to send with POST method

5.2.3 WebAPI Specification#

Regarding the operations that can be performed by the API, the outline, request method and response are listed here. By understanding the API specification and sending the same request from various programs, it is possible to use them from various programming languages and to collaborate with control programs.

For detailed API specification documentation, see External API Interface. If the link is not accessible, please refer to this site.

5.2.3.1 Common Items#

The following list is common to the contents shown in the sample requests thereafter.

Replace with the host port where SpeeDBee Synapse is running.
Replace with the access token issued in “Publish access token”.
specifies the ID of the panel you want to retrieve. This acquires the execution status of all components registered on that panel. You can obtain the panel ID by "Acquire execution status of all components."
specifies the ID of the component whose execution status you want to obtain. You can obtain the component ID by "Acquire execution status of all components."

5.2.3.2 Acquire the execution status of all components#

Overview

This acquires the execution status of all components registered on SpeeDBee Synapse.

Request URL

http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/status

Requests with the curl command

LinuxWindows

$ curl -X "GET" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <Access token>"

$ curl.exe -X "GET" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <Access token>"

Response

Code	Description
200	Normal
403	Authentication error
503	SpeeDBee Synapse is unable to process requests.

A successful response has the following format:

{
  "status": "Status of SpeeDBee Synapse",
  "components": [
    {
      "id": "Component ID",
      "name": "Component name”,
      "panel_id": "ID of the panel in which the component is registered ",
      "panel_name": "Name of the panel in which the component is registered ",
      "status": "Component Status ",
      "errors": [
        {
          "id": "Error ID",
          "parameter": ["Error Message"]
        }
      ]
    }
  ]
}

Note 1: "components" stores the execution state of the components. If there are no components, this is an empty array.
Note 2: "errors" stores error information for the component. If there are no errors, this is an empty array.

5.2.3.3 Acquire the execution status of individual component#

Overview

This acquires the execution status of an individual component registered on SpeeDBee Synapse.

Request URL

http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/status

Requests with the curl command

Per Panel

LinuxWindows

$ curl -X "POST" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <Access token>" -H 'Content-Type: application/json' -d "{\"panel_ids\": [<Panel ID>]}"

$ curl.exe -X "POST" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"panel_ids\": [<Panel ID>]}"

Per Component

LinuxWindows

$ curl -X "POST" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <Access token>" -H 'Content-Type: application/json' -d "{\"component_ids\": [\"<Component ID>\"]}"

$ curl.exe -X "POST" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"component_ids\": [\"<Component ID>\"]}"

Response

Code	Description
200	Normal
403	Authentication error
422	Validation error
503	SpeeDBee Synapse is unable to process requests.

A successful response has the following format:

{
  "status": "Status of SpeeDBee Synapse",
  "components": [
    {
      "id": "Component ID",
      "name": "Component name”,
      "panel_id": "ID of the panel in which the component is registered ",
      "panel_name": "Name of the panel in which the component is registered ",
      "status": "Component Status ",
      "errors": [
        {
          "id": "Error ID",
          "parameter": ["Error Message"]
        }
      ]
    }
  ]
}

Note 1: "components" stores the execution state of the specified component. If there are no components, this is an empty array.
Note 2: "errors" stores error information for the component. If there are no errors, this is an empty array.

5.2.3.4 Start batch execution of components#

Overview

This starts component registered on SpeeDBee Synapse.

Request URL

http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/start

Requests with the curl command

Per Panel

LinuxWindows

$ curl -X "PUT" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/start" -H "accept: application/json" -H "x-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"panel_ids\": [<Panel ID>]}"

$ curl.exe -X "PUT" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/start" -H "accept: application/json" -H "x-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"panel_ids\": [<Panel ID>]}"

Per Component

LinuxWindows

$ curl -X "PUT" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/start" -H "accept: application/json" -H "x-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"component_ids\": [\"<Component ID>\"]}"

$ curl.exe -X "PUT" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/start" -H "accept: application/json" -H "x-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"component_ids\": [\"<Component ID>\"]}"

Response

Code	Description
200	Normal
400	Component cannot start executing due to insufficient points.
403	Authentication error
422	Validation error
503	SpeeDBee Synapse is unable to process requests.

A successful response has the following format:

[
  {
    "id": "Component ID",
    "panel_id": "Panel ID",
    "success": "Component start success or failure ",
    "error": "Error Information"
  }
]

Note: The successful response array contains the list of components specified in the request. If there are no components, this is an empty array.

5.2.3.5 Stop batch execution of components#

Overview

This stops components registered on SpeeDBee Synapse.

Request URL

http://<SpeeDBee Synapse Host Ports>/ext_api/v1/components/stop

Requests with the curl command

Per Panel

LinuxWindows

$ curl -X "PUT" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/stop" -H "accept: application/json" -H "x-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"panel_ids\": [<Panel ID>]}"

$ curl.exe -X "PUT" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/stop" -H "accept: application/json" -H "x-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"panel_ids\": [<Panel ID>]}"

Per Component

LinuxWindows

$ curl -X "PUT" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/stop" -H "accept: application/json" -H "x-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"component_ids\": [\"<Component ID>\"]}"

$ curl.exe -X "PUT" "http://<SpeeDBee Synapse Host: Ports>/ext_api/v1/components/stop" -H "accept: application/json" -H "x-hive-api-key: <Access token>" -H "Content-Type: application/json" -d "{\"component_ids\": [\"<Component ID>\"]}"

Response

Code Description

200 Normal

403 Authentication error

422 Validation error

503 SpeeDBee Synapse is unable to process requests.

A successful response has the following format:
```
[
  {
    "id": "Component ID",
    "panel_id": "Panel ID",
    "success": "Component stop success or failure ",
    "error": "Error Information"
  }
]
```
Note: The successful response array contains the list of components specified in the request. If there are no components, this is an empty array.