- 09 Jun 2023
- 9 Minutes to read
- Print
- PDF
N3uron REST API calls
- Updated on 09 Jun 2023
- 9 Minutes to read
- Print
- PDF
Alarm calls
N3uron REST API alarm calls provide information about the status and monitoring of alarms, and provide operations that can be made on alarms. In order to execute the desired command, alarm calls should start with http://<IP_address>:<HTTP_port>/alarm or https://<IP_address>:<HTTPS_port>/alarm, followed by '?' and the parameters (key-values). The character '&' should be used to separate each parameter.
<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).
Alarm GET commands
Get
Retrieves a list of alarms in the target node.
- template:
https://<IP_address>:<HTTPS_port>/alarm?cmd=get&path=<path>&options.filter.path=<path_filter>
- example:
https://127.0.0.1:3443/alarm?cmd=get&path=/SITE01/LINE01/MACHINE01/ALARMS/&options.filter.path=TEMPERATURE
- parameters:
- path: Path to browse for alarms. (Optional parameter)
- options:
- recurrent: Include subgroups. (Optional parameter)
- filter: Filter parameters include :
- path: Full alarm path regex filter (Optional parameter)
- status: Status to filter, from 0 to 3 (0: Cleared and acked, 1: Active and acked 2: Cleared and unacked 3: Active and unacked). (Optional parameter)
- priority: Minimum priority (1: Low, 2: Medium, 3: High, 4: Critical). (Optional parameter)
A concrete example of this command can be found in the Examples section of the manual.
Count
Request the alarm count.
- template:
https://<IP_address>:<HTTPS_port>/alarm?cmd=count
- example:
https://127.0.0.1:3443/alarm?cmd=count&path=/SITE01/LINE01/MACHINE01/ALARMS/&options.recurrent=true
- parameters:
- path: Path to browse for alarms (optional parameter)
- options:
- recurrent: Include subgroups.
- filter: Filter include parameters:
- path: Full alarm path regex filter (optional parameter)
- status: Status to filter, from 0 to 3 (0: Cleared and acked, 1: Active and acked 2: Cleared and unacked 3: Active and unacked) (optional parameter)
- priority: Minimum priority (1: Low, 2: Medium, 3: High, 4: Critical) (optional parameter)
History
Retrieves historical data of a specific alarm.
- template:
https://<IP_address>:<HTTPS_port>/alarm?cmd=history&path=<path>&start=<start_date>&end=<end_date>
- example:
https://127.0.0.1:3443/alarm?cmd=history&path=SITE01/LINE04/MACHINE01/GEARING/COS021&start=2020-12-07T00:00Z&end=2021-07-07T00:00
- parameters:
- path: Alarm path (mandatory parameter)
- start: Start date. Must be an ISO string or a Unix epoch timestamp (mandatory parameter)
- end: End date. Must be an ISO string or a Unix epoch timestamp (mandatory parameter)
- options:
- recurrent: Include subgroups.
- filter: Filter parameters include:
- path: Full alarm path regex filter (Optional parameter)
- status: Status to filter, from 0 to 3 (0: Cleared and acked, 1: Active and acked 2: Cleared and unacked 3: Active and unacked) (Optional parameter)
- priority: Minimum priority (1: Low, 2: Medium, 3: High, 4: Critical). (Optional parameter)
A concrete example of this command can be found in the Example section of the manual.
Alarm POST commands
Ack
Acknowledges alarms.
- template:
https://<IP_address>:<HTTPS_port>/alarm?cmd=ack
- body template:
{
"paths": "<path>"
}
- parameters:
- paths: Alarm paths. Can be a single alarm, a comma-separated list or a JSON array (Mandatory parameter)
- msg: Message to append to this acknowledgement (Optional parameter)
A concrete example of this command can be found in the Examples section of the manual.
Backup calls
N3uron REST API Server backup calls provide information about the status of configuration backups, and provide operations that can be made on backups. In order to execute the desired command, backup calls should start with http://<IP_address>:<HTTP_port>/backup or https://<IP_address>:<HTTPS_port>backup, followed by '?' and the parameters (key-values). The character '&' should be used to separate each parameter.
<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).
Backup GET commands
Get command
Retrieves a list of current configuration backups.
- template:
https://<IP_address>:<HTTPS_port>/backup?cmd=get
Export command
Retrieves configuration backup in zip format encoded in Base64.
- template:
https://<IP_address>:<HTTPS_port>/backup?cmd=export&name=<backup_name>
- example:
https://127.0.0.1:3443/backup?cmd=export&name=20210504_RestApiServer_01
- parameter:
- name: Name of the backup file (Mandatory parameter)
A concrete example of this command can be found in the Examples section of the manual.
Backup POST commands
Create command
Creates a configuration backup of the target node.
- template:
https://<IP_address>:<HTTPS_port>/backup?cmd=create
- body template:
{
"name": "<name>"
}
- parameters:
- path: Name of the backup file (Mandatory parameter)
- metadata:
- description: Description of the backup file (Optional parameter)
Rename command
Renames a configuration backup.
- template:
https://<IP_address>:<HTTPS_port>/backup?cmd=rename
- body template:
{
"name": "<name>",
"rename": "<new_name>"
}
- parameters:
- name: Name of the backup file (Mandatory parameter)
- rename: New name of the backup file (Mandatory parameter)
Delete command
Deletes a configuration backup.
- template:
https://<IP_address>:<HTTPS_port>/backup?cmd=delete
- body template:
{
"name": "<name>"
}
- parameters:
- name: Name of the backup file (Mandatory parameter)
Import command
Imports a previously exported configuration backup encoded in Base64.
- template:
https://<IP_address>:<HTTPS_port>/backup?cmd=import
- body template (example):
{
"name": "<name>",
"data":
"UEsDBAoAAAAAAJhipFIAAAAAAAAAAAAAAAAKAAAASGlzdG9yaWFuL1BLAwQKAAgACACYYqRSAAAAAAAAAAAAAAAAEQAAAEhpc3Rvcmlhbi9hcGkubjNjTU5LCsIwEL3LrLNIKsbSnRdQcStdtOYJo2kjaVKEkrs7KgVX83nfhWbEicNIzUJDxzKNIjhOIcpaFEVM2SdqLnTbQc5L+yuQ1pM8vw3Xp3qOhlMz/X9CTqk1EXEhVxld3Yh6+g/I4juPwqlO493Ovvysx6+6Gsn9uiSKVu22pK0wexfJT3msR6MIck4L/uxwZe+OOSTWNtgqDyGufIxRdFkLN6T7ct4NNDAa+WPHcYJWr6NLuiNJ56QVzQZtPonqsZYADENaxyiqHDmyZsvjm+41eknLACxIUlCjkA4AuJtRlPsvBq2MI1zxPwYkTX6v8PhBX5uNcwmYRYqS9AlJw57b0L8Ikgo4FoQ7UdJSmd0lqZRxA/i7QWoB7Sbh05lXyydzIWbbJA0FaQW0n4BmP8/J2z2kOL6oSlQLwjrGKB6
…
ipFIAAAAAAAAAAAAAAAAUAAAAYm9vdHN0cmFwL2xvZ2dlci5uM2N1T8sKwjAQ/Jc5B6FqW9ujH6AHj6WHtNlKJE0gTYsS8u9uQBAPsod9zs5MxEZ+0c6ijZil5lwIkNLBeS6TgKdlNQFth+vwoDFARIzOLs7Q75CsHAwptMGvJGBoI4MWwcuRkHqBSf+FdDg7figtREbz8Qfe4Ra8tncIaDs58EbJ15KZL+s8kIeo+8TxFR1Bz0BW8RFbcmrNrNiBvXCnJ501FmVzaqqm3FfH+pDSG1BLBwgaUmq1rQAAAAcBAABQSwMECgAIAAgAmGKkUgAAAAAAAAAAAAAAABUAAABib290c3RyYXAvbW9kdWxlcy5uM2PVU8FKQzEQ/Jc9B8nTWqE39aKXCj7Eg/SQZ7aogIjEuMi4xLTIwMDQwMS4yMjA4IiwKICAgICJGbGVldE1hbmFnZXJDbGllbnQiOiAiMS4wLjAtMjEwNDE2LjExMDItYmV0YSIKICB9Cn0="
}
}
- parameters:
- name: Name of the backup file (Mandatory parameter)
- data: Backup file data, encoded in Base64 (Mandatory parameter)
Load command
Applies a configuration backup to the current node.
- template:
https://<IP_address>:<HTTPS_port>/backup?cmd=load
- body template:
{
"name": "<name>"
}
- parameters:
- name: Name of the backup file (Mandatory parameter)
Module calls
N3uron REST API Server module calls provide information about the status and monitoring of each module and operations that can be made on modules. In order to execute the desired command, module calls should start with http://<IP_address>:<HTTP_port>/module or https://<IP_address>:<HTTPS_port>/module, followed by '?' and the parameters (key values). The character '&' should be used to separate each parameter.
<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).
Module GET commands
Details command
Retrieves full details of instanced modules.
- template:
https://<IP_address>:<HTTPS_port>/module?cmd=details
GetInstalled command
Retrieves the list of installed modules.
- template:
https://<IP_address>:<HTTPS_port>/module?cmd=getInstalled
- parameters:
- filter: Module names. Can be a single filter, a comma-separated list or a JSON array (Optional parameter)
GetInstances command
Retrieves a list of instanced modules in the target node.
- template:
https://<IP_address>:<HTTPS_port>/module?cmd=getInstances
- parameters:
- filter: Module names. Can be a single filter, a comma-separated list or a JSON array (Optional parameter)
GetConfigList command
Retrieves a list of configuration files for every type of module.
- template:
https://<IP_address>:<HTTPS_port>/module?cmd=getConfigList&moduleType=<module_type>
- example:
https://127.0.0.1:3443/module?cmd=getConfigList&moduleType=SiemensClient
- parameters:
- moduleType: Module type (Optional parameter)
GetConfigPresent command
Indicates whether or not the configuration files for a specific module instance exist.
- template:
https://<IP_address>:<HTTPS_port>/module?cmd=getConfigPresent&moduleName=<module_name>
- example:
https://127.0.0.1:3443/module?cmd=getConfigPresent&moduleName=Siemens
- parameters:
- moduleName: Module instance name (Optional parameter)
GetConfigData command
Retrieves configuration file content for a specific module instance.
- template:
https://<IP_address>:<HTTPS_port>/module?cmd=getConfigData&moduleName=<module_name>&configName=<config_name>
- example:
https://127.0.0.1:3443/module?cmd=getConfigData&moduleName=Siemens&configName=logger
- parameters:
- moduleName: Module instance name (Optional parameter)
- configName: Configuration name (Mandatory parameter)
Module POST commands
Start command
Starts a specific module.
- template:
https://<IP_address>:<HTTPS_port>/module?cmd=start
- body template:
{
"moduleName": "<module_name>"
}
- parameters:
- moduleName: Module instance name (Mandatory parameter)
Stop command
Stops a module.
- template:
https://<IP_address>:<HTTPS_port>/module?cmd=stop
- body template:
{
"moduleName": "<module_name>"
}
- parameters:
- moduleName: Module instance name (Mandatory parameter)
Restart command
Restarts a module.
- template:
https://<IP_address>:<HTTPS_port>/module?cmd=restart
- body template:
{
"moduleName": "<module_name>"
}
- parameters:
- moduleName: Module instance name (Mandatory parameter)
SetConfigData command
Sets a configuration file for a specific module instance.
- template:
http://<IP>:<port>/module?cmd=setConfigData
- body template:
{
"moduleName": "<module_name>",
"configName":"<configuration_name>",
"data":"<data>"
}
- example:
http://{{IP_address}}:{{HTTP_port}}/module?cmd=setConfigData
{
"moduleName": "ModuleTest",
"configName":"logger",
"data":"{\"version\":{\"main\":1,\"editor\":1},\"result\":[\"Object\",{\"console\":[\"Object\",{\"enabled\":true,\"level\":\"trace\"}],\"file\":[\"Object\",{\"enabled\":[\"Boolean\",true],\"level\":[\"String\",\"info\"],\"days\":[\"Number\",7]}]}],\"editor\":{\"extends\":{\"module\":null},\"modified\":1582974868907}}"
}
- parameters:
- moduleName: Module instance name (Mandatory parameter)
- configName: Configuration name (for example: logger, API, users, tags, views, links, etc.) (Mandatory parameter)
- data: Configuration file in JSON format (Mandatory parameter)
- options:
- restart: Restart module after saving new configuration (Optional parameter)
- deleteData: Only applicable to module configuration file. List of deleted module instances to clean their data. Can be a single instance, a comma-separated list or a JSON array (Optional parameter).
Link calls
N3uron REST API Server link calls provide operations and information about the status of the links in the target node. In order to execute the desired command, link calls should start with http://<IP_address>:<HTTP_port>/link or https://<IP_address>:<HTTPS_port>/link, followed by '?' and the parameters (key values), using '&' to separate each parameter.
<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).
Links GET commands
Get command
Retrieves current links.
- template:
https://<IP_address>:<HTTPS_port>/link?cmd=get
License calls
N3uron REST API Server link calls provide operations and information about the status of licenses in the target node. In order to execute the desired command, license calls should start with http://<IP_address>:<HTTP_port>/license or https://<IP_address>:<HTTPS_port>/license, followed by '?' and the parameters (key values), using '&' to separate each parameter.
<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).
License GET commands
GetUid command
Retrieves current node UID.
- template:
https://<IP_address>:<HTTPS_port>/license?cmd=getUid
Get command
Retrieves a list of licenses of this node.
- template:
https://<IP_address>:<HTTPS_port>/license?cmd=get
Read command
Retrieves details of a specific license.
- template:
https://<IP_address>:<HTTPS_port>/license?cmd=read&name=<license_name>
- example:
https://127.0.0.1:3443/license?cmd=read&name=DataServer01-20210216.143244.n3l
- parameters:
- name: Name of the license file (Mandatory parameter)
License POST commands
Add command
Adds a license to the target node.
- template:
https://<IP_address>:<HTTPS_port>/license?cmd=add
- body template:
{
"data": "{\"version\":\"1\",\"created\":\"2021-01-05T14:43:16.652Z\",\"signature\":\"5ce1ff1b7a9f911b49f653aa291bd375d8b2c53a0d57b0958ffe5f2341d",\"count\":1},{\"type\":\"SiemensClient\",\"tagAccess\":\"local\",\"count\":1},{\"type\":\"SmaClient\",\"tagAccess\":\"local\",\"count\
...
":1},{\"type\":\"SqlClient\",\"tagAccess\":\"remote\",\"count\":1},{\"type\":\"UflExporter\",\"tagAccess\":\"remote\",\"count\":1},{\"type\":\"WebVision\",\"tagAccess\":\"remote\",\"count\":1},{\"type\":\"XantrexClient\",\"tagAccess\":\"local\",\"count\":1}]}]}" }
- parameters:
- data: Data of the license file in JSON format (Mandatory parameter)
Remove command
Deletes a license in the target node.
- template:
https://<IP_address>:<HTTPS_port>/license?cmd=remove
- body template:
{
"name": "<license_name>"
}
- parameters:
- name: Name of the license file (Mandatory parameter)
System calls
N3uron REST API Server system calls provide operations and information about the status and monitoring of the target node. In order to execute the desired command, system calls should start with http://<IP_address>:<HTTP_port>/system or https://<IP_address>:<HTTPS_port>/system, followed by '?' and the parameters (key values). The character '&' should be used to separate each parameter.
<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).
System GET commands
Status command
Retrieves information regarding the status of the host system, current hardware, hostname, uptime, etc.
- template:
https://<IP_address>:<HTTPS_port>/system?cmd=status
Errorcount command
Retrieves the number of errors in the current node. If there are no errors, 0 is returned, otherwise, it returns the number of errors (these can be caused by invalid tag configuration, invalid link configuration, etc...).
- template:
https://<IP_address>:<HTTPS_port>/system?cmd=errorCount
System POST commands
RestartService command
Restarts service.
- template:
https://<IP_address>:<HTTPS_port>/system?cmd=restartService
Tag calls
N3uron REST API Server tag calls provide write operations and information about the status and monitoring of tags in the target node. In order to execute the desired command, tag calls should start with http://<IP_address>:<HTTP_port>/tag or https://<IP_address>:<HTTP_port>/tag, followed by '?' and the parameters (key values). The character '&' should be used to separate each parameter.
<IP_address> must be replaced by the server's IP address and <HTTP_port> and <HTTPS_port> must be replaced by the port assigned to the REST API Server (3003 by default for HTTP requests and 3443 by default for HTTPS requests).
Tags GET commands
Browse command
Retrieves a list of tags present in the defined path.
- template:
https://<IP_address>:<HTTPS_port>/tag?cmd=browse&path=<path>
- example:
https://127.0.0.1:3443/tag?cmd=browse&path=/SITE01/LINE01/MACHINE01/
- parameters:
- path: Path to browse for tags (Optional parameter)
- options:
- filter: Full tag path regex (Optional parameter)
- flat: Receive an array instead of an object (Optional parameter)
- recurrent: Include subgroups (Optional parameter)
- hideTags: Do not receive tags (Optional parameter)
- hideGroups: Do not receive groups (Optional parameter)
Read command
Retrieves values of tags present in the defined path.
- template:
https://<IP_address>:<HTTPS_port>/tag?cmd=read&path=<path>
- example:
https://127.0.0.1:3443/tag?cmd=read&path=/SITE01/LINE01/MACHINE01/*
- parameters:
- path: Path to read tag (Optional parameter)
- options:
- filter: Path to read tags. Entire groups can read using a wildcard * (Optional parameter)
- recurrent: Include subgroups (Optional parameter)
A concrete example of this command can be found in the Examples section of the manual.
Details command
Retrieves full details of tags present in the defined path.
- template:
https://<IP_address>:<HTTPS_port>/tag?cmd=details&path=<path>
- example:
https://127.0.0.1:3443/tag?cmd=details&path=/SITE01/LINE01/MACHINE01/*
- parameters:
- path: Path to read tag (Mandatory parameter)
- options:
- filter: Path to read tags. Entire groups can read using a wildcard * (Optional parameter)
- recurrent: Include subgroups (Optional parameter)
History command
Retrieves historical data of a specific tag.
- template:
https://<IP_address>:<HTTPS_port>/tag?cmd=history&path=<path>&start=<start_date>&end=<end_date>
- example:
https://127.0.0.1:3443/tag?cmd=history&path=/SITE01/LINE01/MACHINE01/AMPLITUDE&start=1619707394591&end=2021-04-29T15:10:51.174Z
- parameters:
- path: Tag path. (Mandatory parameter)
- start: Start date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
- end: End date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
- options:
- mode: Historical data modes. Can be raw, filter, delta or aggregated. default setting: delta (Optional parameter)
- method: Aggregation method when using aggregated mode. Can be first, last, min, max. and avg. Set to an empty value to get default method in the tag configuration (Optional parameter)
- interval: Aggregation interval when using aggregated mode, in milliseconds (Optional parameter)
- deadband: deadband when using filter or delta mode (Optional parameter)
- invalidAsNull: Convert non-good quality values to null when using raw mode. (Optional parameter, by default it's enabled).
- limit: Maximum number of samples to return when using raw mode. (Optional parameter).
A concrete example of this command can be found in the Example section of the manual.
HistoryMany command
Retrieves historical data of tags.
- template:
https://<IP_address>:<HTTPS_port>/tag?cmd=historyMany&paths=<path>&start=<start_date>&end=<end_date>
- example:
https://{{IP_address}}:{{HTTPS_port}}/tag?cmd=historyMany&paths=/SITE01/LINE01/MACHINE01/AMPLITUDE,/SITE01/LINE01/MACHINE01/COS_1DAY_PLC&start=1619707394591&end=2021-09-29T15:10:51.174Z
- parameters:
- paths: Tag path list. Can be a single tag, a comma-separated list or a JSON array (Mandatory parameter)
- start: Start date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
- end: End date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
- options:
- mode: Historical data modes. Can be raw, filter, delta or aggregated. default setting: delta (Optional parameter)
- method: Aggregation method when using aggregated mode. Can be first, last, min, max and avg. Set to an empty value to get default method in the tag configuration (Optional parameter)
- interval: Aggregation interval when using aggregated mode, in milliseconds (Optional parameter)
- deadband: Deadband when using filter or delta mode (Optional parameter)
- invalidAsNull: Convert non-good quality values to null when using raw mode. (Optional parameter, by default it's enabled).
- limit: Maximum number of samples to return when using raw mode. (Optional parameter).
HistoryFilter command
Retrieves historical data of tags (with regex filter).
- template:
https://<IP_address>:<HTTPS_port>/tag?cmd=historyFilter&path=<path>&start=<start_date>&end=<end_date>&options.filter=<tag_path>
- example:
https://127.0.0.1:3443/tag?cmd=historyFilter&path=/SITE01/LINE01/MACHINE01&start=1619707394591&end=2021-04-29T15:10:51.174Z&options.filter=AMPLITUDE
- parameters:
- paths: Tag path list. Can be a single tag, a comma-separated list or a JSON array (Mandatory parameter)
- start: Start date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
- end: End date. Must be an ISO string or a Unix epoch timestamp (Mandatory parameter)
- options:
- filter: Full tag path Regex filter (Optional parameter)
- recurrent: Include subgroups (Optional parameter)
- mode: Historical data modes. Can be raw, filter, delta or aggregated. default setting: delta (Optional parameter)
- method: Aggregation method when using aggregated mode. Can be first, last, min, max and avg. Set to an empty value to get default method in the tag configuration (Optional parameter)
- interval: Aggregation interval when using aggregated mode, in milliseconds (Optional parameter)
- deadband: Deadband when using filter or delta mode (Optional parameter)
- invalidAsNull: Convert non-good quality values to null when using raw mode. (Optional parameter, by default it's enabled).
- limit: Maximum number of samples to return when using raw mode. (Optional parameter).
Views command
Retrieves tag views.
- template:
https://<IP_address>:<HTTPS_port>/tag?cmd=getViews
Tags POST commands
Write command
Writes a specific tag value.
- template:
https://<IP_address>:<HTTPS_port>/tag?cmd=write
- body template:
{
"path": "<tag_path>",
"value": <value>
}
- parameters
- path: Tag path (Mandatory parameter)
- value: Value to write. The type must be the same as the configuration (number, Boolean or string) (Mandatory parameter)
A concrete example of this command can be found in the Examples section of the manual.