Configuration

Module Configuration

By selecting REST API Server in the explorer tree menu, users can configure how the module will accept connections. The following screenshot shows the different available options for REST API Server Configuration:

Parameters:

Mode: Specifies what protocols will be accepted by the REST API Server. Available options are “HTTP”, “HTTPS” and “Both (HTTP & HTTPS)”.

HTTP:

• TCP port: specifies the HTTP port number for connecting to the REST API Server. The default port number is 3003. The valid range is 1 to 65535. This port may not be used by any other application on the same machine.
• Network interface: Specifies the interface for accessing the REST API Server via HTTP. You can either select the network interface by clicking the browse button or enter the IP address manually.

  
  
  

HTTPS:

• TCP port: Specifies the HTTPS port number for connecting to the REST API Server. The default port number is 3443. The valid range is 1 to 65535. This port may not be used by any other application on the same machine.
• Network interface: Specifies the interface for accessing the REST API Server via HTTPS. You can either select the network interface by clicking the browse button or enter the IP address manually
• Certificate type: Specifies the server HTTPS certificate. The following options are available:
  • Self-signed: The server will create and sign a certificate automatically using an internal certification authority that can be downloaded in the Self-signed certificate menu (as shown in the image below). This certification authority is valid for all the REST API Server instances and must be imported into each system/web client that will access the REST API Server via HTTPS. When selecting the “Self-signed” option, the following section will appear:
    • Self-signed certificate parameters:
      • Certified hosts: Comma-separated host list (domains/host names and/or IPs) that will be included in the auto-generated SSL certificate. It is important to include all the hosts where the REST API Server will be accessed so the web client does not show any errors. Hosts 127.0.0.1, localhost and system hostname will be automatically added to the certificate.

• • Embedded: The provided certificates will be embedded in the configuration file. When selecting the “Embedded” option, the following section will appear:
    • Custom certificate parameters:
      • Key: Certificate key in PEM format.
      • CA bundle/chain: Optional. CA bundle in PEM format.
      • Certificate: Certificate in PEM format.
  • File path: File path where the certificate files are located, with a hot-reload option. The path is relative to the data/<instance name>/cert/ folder. When selecting the “File path” option, the following section will appear:
    • File path certificate parameters:
      • Key path: Certificate key in PEM format. The path is relative to the data/<instance name>/cert/ folder.
      • CA bundle/chain: Optional. Certificate CA bundle in PEM format. The path is relative to the data/<instance name>/cert/ folder. The file will not be reloaded, so it is necessary to restart the module if the file is modified while the module is running.
      • Certificate path: Certificate in PEM format. The path is relative to the data/<instance name>/cert/ folder.
      • Reload interval: Expressed in seconds, specifies the interval to reload certificates if file changes were detected. Set to 0 to disable.

Access Configuration

The REST API Server uses authorization to ensure secure data access. This includes authenticating the sender and verifying their permission to access or manipulate data.

Currently, two types of authorization are supported: Role authentication, which involves sending a verified username and password, and Token authentication, which uses an API key.

Role Authentication 

Selecting this option, permissions will be assigned to the Roles previously created in the Roles section.

Parameters:

• Enabled: Specifies whether or not any authentication attempt will be blocked. 
• API Access: N3uron REST API calls use the GET and POST methods and can be categorized into the following groups:
  • Alarm: Access to tag alarms namespace.
  • Backup: Access to the node backup system.
  • Certificate: Access to the node certificate system.
  • License: Access to the node licensing system.
  • Link: Access node link system.
  • Module: Access modules system.
  • System: Access node system namespace.
  • Tag: Access tag namespace.
• Tag access: 
  • Tag Filter: Define and configure the filter for tags to be included in the message.
    Note:

    It is mandatory to add a filter even when the whole model is going to be published.
    • Mode: Specifies whether the filter must include or exclude tags. 
      Note:

      Include filters are applied first and exclude filters are applied to the include filters' results.
    • Path: Specifies the path of the tag or group of tags to be filtered. 
    • Regex Pattern: This is a regular expression for filtering which tags will be included. By default, it is set to .*, meaning no filter is applied. Readers can find further information about regular expressions at RegExr.

Token Authentication

This option enables requests to authenticate using an access key. The token is a text string, included either in the request header or passed as a parameter.

Parameters:

• Enabled: Specifies whether or not any authentication attempt will be blocked. 
• Token: API key value autogenerated by clicking on the button on the right side. Authentication can be made using two methods: GET parameter and HTTP header.
  • An example, being the token 123ABC:
    • GET parameter: Adding the bearer token in a token URL parameter. Example: https://<address>:<port>/module?cmd=details&token=123ABC.
    • HTTP header: Adding the bearer token to the HTTP Authorization header. Example: Authorization: Bearer 123ABC.
• API Access: N3uron REST API calls use the GET and POST methods and can be categorized into the following groups:
  • Alarm: Access to tag alarms namespace.
  • Backup: Access to the node backup system.
  • Certificate: Access to the node certificate system.
  • License: Access to the node licensing system.
  • Link: Access node link system.
  • Module: Access modules system.
  • System: Access node system namespace.
  • Tag: Access tag namespace.
• Tag access: 
  • Tag Filter: Define and configure the filter for tags to be included in the message.
    Note:

    It is a mandatory to add a filter even when the whole model is going to be published.
    • Mode: Specifies whether the filter must include or exclude tags. 
      Note:

      Include filters are applied first and exclude filters are applied to the include filters' results.
    • Path: Specifies the path of the tag or group of tags to be filtered. 
    • Regex Pattern: This is a regular expression for filtering which tags will be included. By default, it is set to .*, meaning no filter is applied. Readers can find further information about regular expressions at RegExr.

REST API Server Full Product Details