The Rest API is always available at the following address:
https://localhost:22722/api/{Ressource}
Depending on the selected authentication, you still need to pass username and password in the header (Basic) in each request. How exactly you set the Basic authentication depends on your client.
All information is always transferred in JSON format.
Evaluate error codes #
The following HTTP status codes are returned. If the request ended with an error, an error object containing an error message is returned for the error code.
| HTTP Code | Description |
| 200 | Request successfully executed. |
| 400 | Bad Request: Request could not be executed. Parameters are invalid. |
| 401 | Unauthorized: Authentication (username/password) is invalid. |
| 403 | Forbidden: Access to the resource is set to “No access” in the web server/rest API settings. |
| 404 | Not Found: The address was not found. |
Object: Error
| Parameter | Type Description | Type Description |
| code | string HTTP Status Code | string HTTP Status Code |
| message | string error message | string error message |
PLC – end points #
Query all controls (Get) #
The api/plcs endpoint provides you with a list of all enabled controllers.
GET
https://localhost:22722/api/plcs
Parameter: None
Response: Collection of PLC objects (JSON).
Object: PLC
| Parameter | Type | Description |
| name | string | Name of the PLC |
| ip | string | IP address of the PLC. For the simulator it is [MB] Simulator |
| plcType | string | PLC type Simulator, S7-300, S7-1200, S7-… |
| connectionType | string | Connection type: [MB] Simulator S7 OPC UA |
| connectionState | int | Connection status: 0 = Disconnected 1 = Connection is established 2 = Connected |
| dataBlocks | String listing | All imported data blocks |
Querying variables of a data block (Get) #
Via the endpoint api/plcs/{PLC-name}/datablocks/{DB-name}/variables you get a list of all PLC variables in this data block.
GET
https://localhost:22722/api/plcs/{ PLC -Name}/datablocks/{DB-Name}/variables
https://localhost:22722/api/plcs/PLC/datablocks/Data/variables
Parameter: The parameters PLC-Name and DB-Name are required.
| Parameter | Type | Description |
| PLC-Name | string | Name of the PLC |
| DB-Name | string | Name of the data block |
Response: Listing of the variables of the data block as variable object (JSON).
Object: Variable
| Parameter | Type | Description |
| name | string | Name of the PLC |
| fullName | string | Full name of the variable. If the variable is e.g. inside a struct: StructName.VariableName |
| dataType | String | S7 Data type |
| variables | Variable type listing | Contains all nested variables, e.g. for structs or arrays. |
Query variable values (Get) #
You can query variable values via the api/plcs/{PLC-name}/datablocks/{DB-name}/values?variables=… endpoint.
GET
https://localhost:22722/api/plcs/{PLC-Name}/datablocks/{DB-Name}/values
?variables={Variable-Name},{Variable-Name}
https://localhost:22722/api/plcs/PLC/datablocks/Data/values
?variables=Order,Product
You can either query a single variable or several variables at once. If you want to read multiple variables, simply specify the names of the variables separated by a comma. All variables must be in the same data block.
Parameter: The parameters PLC-Name, DB-Name and Variable-Name are required.
| Parameter | Type | Description |
| PLC-Name | string | Name of the PLC |
| DB-Name | string | Name of the data block |
| Variable-Name | string | Name of one or more variables. Multiple variables are separated by a comma. |
| mode (optional) | string | If Mode is set to raw, no information about the variables is returned, only the value. |
Response: Listing of the variables of the data block as variable object (JSON).
Object: Variable
| Parameter | Type | Description |
| name | string | Variable name |
| dataType | string | S7 Data type |
| value | Depending on the type of the variable | Depends on the type of the variable. Will be explained in the following paragraph. |
The value of a variable depends on the data type of the variable. A distinction is made between the four possibilities:
1. Simple value data type
For simple data types, such as Byte, Int, String, the simple value is returned as Value.
2. Struct data type
For a Struct, Value contains a list of the object type Variable.
3. Array data type
For an array, Value contains a listing of the object type variable. Each element of the array is specified as a complete variable.
4. Struct array data type
In a Struct array, Value contains a list of the object type Variable (Struct). Each element in the list is a Struct, which in turn contains a list of the object Variable in Value.
Writing variable values (post) #
You can write variable values to the PLC via the api/plcs/{PLC-name}/datablocks/{DB-name}/values endpoint. There are two ways to write variables.
Transferring variable values directly as parameters #
Variable values are passed directly as parameters: {name}={value}. If you want to write multiple variables, you can separate them with a comma.
This method is suitable for writing simple variable values in an uncomplicated way. With this method, the body of the request is left empty.
POST
https://localhost:22722/api/plcs/{PLC-Name}/datablocks/{DB-Name}/values
?variables={Variable-Name}={Variable-Value}
https://localhost:22722/api/plcs/PLC/datablocks/Data/values
?variables=Order=123,Product=abc
Parameter: The parameters PLC-Name, DB-Name, Variable-Name and Variable-Value are required.
| Parameter | Type | Description |
| PLC -Name | string | Name of the PLC |
| DB-Name | string | Name of the data block |
| variables Variable-Name = Variable-Value | string | Name of one or more variables with the assignment of the value. Multiple assignments are separated by a comma. |
Response: Status code 200 (OK). No body is returned.
Passing variable values as JSON body #
If you want to write many variables in one operation, transferring the variable values as JSON body is suitable.
POST
https://localhost:22722/api/plcs/{PLC-Name}/datablocks/{DB-Name}/values
https://localhost:22722/api/plcs/PLC/datablocks/Data/values
Parameter: The parameters PLC-Name, DB-Name, Variable-Name and Variable-Value are required.
| Parameter | Type | Description |
| PLC-Name | string | Name of the PLC |
| DB-Name | string | Name of the data block |
The variable values to be written are transferred in the body of the request. These are transferred as a listing of the variable value object. If you want to write only one value, you can also send only the individual object instead of the listing.
Object Variable value
| Parameter | Type | Description |
| fullName | string | Full name of the variable. For example, if the variable is inside a struct: StructName.VariableName. For array variables: Array[10].ID The name is obtained by querying the available variables of the data block |
| value | object | New variable value |
Transfer of a variable value object
Transferring a collection of variable value objects
Response: Status code 200 (OK). No body is returned.
Trigger – end points #
You can use the api/trigger endpoint to get a listing of all triggers available via the Rest API.
Get
https://localhost:22722/api/trigger
Parameter: None
Response: Listing of triggers (JSON).
Object: Trigger
| Parameter | Type | Description |
| name | string | Name of the trigger |
| group | string | Trigger group |
| isEnabled | Bool | Indicates whether the trigger is activated. False = Trigger is deactivated, is not monitored, cannot be started. True = Trigger is activated, is monitored, can be started. |
| actions | String type listing | Description of all actions defined in the trigger |
Start trigger (post) #
You can start a trigger via the api/trigger/{trigger-name}/start endpoint.
Post
https://localhost:22722/api/trigger/{Trigger-Name}/start
Parameter: The Trigger name parameter is required.
| Parameter | Type | Description |
| Trigger-Name | string | Trigger name |
Response: Status code 200 (OK). No body is returned.
