REST¶

Characteristics - REST¶

Representational state transfer (REST) is a software architectural style that describes a uniform interface between decoupled components in the Internet in a Client-Server architecture. To learn more about the standard visit the REST section in Wikipedia website.

The characteristics of a REST server that need to be configured typically include the following:

• Host and Port: The network address (IP or hostname) and port number on which the server listens for incomming HTTP requests.

• Base URL/Context Path: The root path under which the REST API is accessible (e.g. /api/v1).

• SSL/TLS (HTTPS): Certificates and protocols used for secure communication.

• Message Encoding: The character encoding used for the body of HTTP requests and responses.

• Timeouts: Limits for request processing time, connection time, etc.

• Endpoint/Routes: The specific URI’s and HTTP methods (GET, POST, PUT, DELETE, etc.) that the server will handle.

• Thread Pool/Concurrency Settings: Limits for the number of concurrent requests the server can handle.

Configuration - REST Server¶

To configure a REST server in SmartUnifier, a few core concepts should be understood:

• Information Model: defines the structure of resources on the server but also detailed configuration of the endpoints/routes (Parametes, Headers, Body structure). In the current version of SmartUnifier only Variables, Complex Variables and Commands can be used for REST server configuration.

• Communication Channel: specifies how the defined structure will be communicated to clients.

Variables and Complex variables can be used together with the rest server as storage for data. For example you have an equipment with all kind of data points like temperature, pressure, etc., these data points can be stored in a complex variable and the rest server can be configured to return the data in a structured way.

Commands can be used to execute actions on the server. Command parameters can be used as headers, url parameters or body content. Command reply can be used retrieve the return code, headers and body of the executed command.

General REST Server channel configuration:¶

Webapp configuration¶

SSL configuration¶

Java Certificate Keystore configuration¶

SmartUnifierManager\jre\bin\keytool.exe -genkeypair -keyalg RSA -keysize 2048 -keystore keystore.jks -alias SmartUnifier3 -dname "CN='smartunifier-https-vhost',OU=amorph.pro,O=Amorphsys,C=DE" -storepass 'changeit' -keypass 'changeit' -validity 3650 -ext KeyUsage=digitalSignature,dataEncipherment,keyEncipherment,keyAgreement -ext ExtendedKeyUsage=serverAuth,clientAuth

SmartUnifierManager\jre\bin\keytool.exe -v -list -keystore keystore.jks -storepass changeit

Windows Certificate Management configuration¶

There are 4 supported stores where the certificate can be placed:

• Local Machine MY Stores certificates and private keys accessible to all accounts on the system.

• Local Machine ROOT Contains root CA certificates and trusted self-signed certificates accessible to all accounts on the system.

• Current User MY Stores personal certificates and private keys accessible only to the current user.

• Current User ROOT Contains root CA certificates and trusted self-signed certificates accessible only to the current user.

New-SelfSignedCertificate -DnsName localhost -CertStoreLocation cert:\LocallMachine\Root

Variable and Complex Variable configuration¶

No configurations are needed for the variable and complex variable nodes. Server will automatically create routes based on the pathPrefix and variable path. E.g. if the pathPrefix = /api/v1 and the variable is created in the root of the information model, with the name temperature, the route will be /api/v1/Variable/temperature. If the variable is created under the Measurements complex variable, the route will be /api/v1/Variable/Measurements/Variable/temperature. But also /api/v1/Variable/Measurements route will be available. For both variable types GET, PUT, POST methods will be available.

Command configuration¶

By default commands are disabled. To enable commands you have to select it in the channel configuration from the information model tree. By checking the “Command routed” you enable that command. If no other configuration is done a default route will be created based on the pathPrefix. E.g. if the pathPrefix = /api/v1 and the command is created in the root of the information model, with the name getTemperature, the route will be /api/v1/Command/getTemperature. As for the variables GET, PUT, POST methods will be available.

Command configuration details¶

Configuration - REST Client¶

The following sample configuration shows a GET request using url parameters.

1. Select the root model node in the tree on the left

2. Select the content type - defines the media type of the associated representation

3. Set the wait timeout

4. Select the Command node

5. Enable the Command routes checkbox for the configuration of the following fields:

   • Enter the URL - If URL parameters are used then add each parameter in the following syntax ${id}

   • Select the HTTP method.

6. Headers (Optional) - Enable the checkbox Headers for the configuration of the following fields:

   • Enter the name of the header

   • Enter the value

7. Add multiple header entries by clicking the Add button

8. Delete a header by clicking the Delete button

9. Select the Authentication type

10. Select the Message encoding standard

11. Check the box to Log data (E.g., the body of a request).

12. URL Parameters (Optional) - Select a custom variable node

13. Enable the Command routes for the configuration of the following fields:

    • Select the Content Type

    • (Optional) Enter a Field Name in case the Information Model Node is not matching the REST API

Description of configuration properties: