This article describes how to configure the SystemWeaver REST API server application. 


Prerequisites

  • A SystemWeaver main server of version R32 or later is installed and configured

  • A compatible SystemWeaver REST API server application is installed

  • For log file output, the account running the REST API server must have Write access to the log file target directory


The SystemWeaver REST API server is configured using the SystemWeaver.RestApi.exe.config file for pre-R35 versions and the appsettings.json file for version R35 and later. Open the file with a text editor such as Notepad or Notepad++.


Configuring the Server

Versions R32-R34

In the SystemWeaver.RestApi.exe.config configuration file, there is a section called appSettings. This section contains the configuration information required for the SystemWeaver REST API server to be set up properly. Below are excerpts from the configuration files.

Example

 <appSettings>    
    <add key="RestApiBaseURL" value="sys76" />
    <add key="RestApiPort" value="9000" />
    <add key="RequireHttps" value="false" />
    <add key="SystemWeaverHost" value="sys76" />  
    <add key="SystemWeaverPort" value="8888" />      
  </appSettings>        

The configuration properties of the SystemWeaver REST API server are described as key-value pairs in the configuration file. When configuring, make sure to only edit the values in the value attributes, e.g., value="{value to set}". Changing the values of the key attributes will result in the SystemWeaver REST API not starting or starting with default values. 


Version R35 or Later

The same settings shown above can be found at the top of the appsettings.json configuration file. 


Example

{
  "SystemWeaver": {
    "restApiBaseURL": "localhost", 
    "restApiPort": 9000,
    "requireHttps": false,  
    "certificateSubjectName": "systemweaver.local",  
    "systemWeaverHost": "localhost",
    "systemWeaverPort": 8888,
    "allowHttp2": true   
  },  
The various settings are explained below:

RestApiBaseUrl: The base url of the SystemWeaver REST API Server that REST Clients will connect to

RestApiPort: The port of the SystemWeaver REST API Server that REST Clients will connect to

RequireHttps: Indicates whether to use HTTPS or not

certificateSubjectName: The Subject of the certificate. Must be set for use of HTTPS.


Example from Manage Computer Certificates:



SystemWeaverHost: The URL of the SystemWeaver server or mirror server that the REST API Server utilizes

SystemWeaverPort:  The port of the SystemWeaver server or mirror server that the REST API Server utilizes

allowHttp2: Indicates whether to enable (true) or disable (false) the use of HTTP2.


Important Note: For production use, HTTPS is strongly recommended to secure the transfer of user credentials between the clients and the server, otherwise the user name and password will be transferred in plain text. Please note that this requires a Certificate. The Certificate must be installed on the same server as the REST API. By default, it would reside in some form of "certificate archive". The certificate must be available in the certificate store (StoreLocation) for Local computer  (LocalMachine) in the Personal (My) folder. From a SystemWeaver perspective, it does not matter if it is an internal or external certification authority. Note that the certificate must be assigned to the port indicated in the RestApiPort setting above.



Configuring Logging

The SystemWeaver REST API uses NLog for logging. There are two main logs produced: 

  • Request log
  • Application log

The Request log logs the API requests from the clients together with their parameters. 

The Application log is a standard application log that logs user logins, server communication, exceptions, etc.  


In the configuration files, there is a section called nlog (or NLog). This section contains the configuration information required for the SystemWeaver REST API server logging to be set up properly. The configuration file is described below, both for Pre-R35 and R35 or later versions. 


Versions R32-R34

The configuration file is SystemWeaver.RestApi.exe.config.

 <nlog>    
    <targets> 
      <target name="console" type="ColoredConsole" layout="${longdate} ${message} ${exception:format=tostring}" />
      <target name="file" type="File" fileName="SystemWeaver.RestApi.log" layout="${longdate} ${message} ${exception:format=tostring}" />
      <target name="requestFile" type="File" fileName="SystemWeaver.RestApi.Request.log" layout="${longdate} ${message}" />
    </targets> 
    <rules> 
      <logger name="SystemWeaver.RestApi.WebService.Setup.RequestLogger" minlevel="Debug" writeTo="console,requestFile" final="true" />
      <logger name="*" minlevel="Debug" writeTo="console,file" />
    </rules>
  </nlog>   

Each target in the configuration represents a different log output. 


Console Logging

The first target with the name "console" outputs logging information into the application's console window. 

 <target name="console" type="ColoredConsole" layout="${longdate} ${message} ${exception:format=tostring}"/>       

This target is not intended to be changed. 


Application Log

The second target with the name "file" outputs the Application log. By default, this log is stored in the same directory as the SystemWeaver REST API executable with the file name "SystemWeaver.RestAPi.log", as defined in the fileName attribute. 

<target name="file" type="File" fileName="SystemWeaver.RestApi.log" layout="${longdate} ${message} ${exception:format=tostring}"/>    

To change the location of the log file, choose another destination and file name and enter that value in the fileName attribute. The below example shows a configuration that saves the log file to "C:/Temp/SystemWeaver.RestApi.log".

<target name="file" type="File" fileName="C:\Temp\SystemWeaver.RestApi.log" layout="${longdate} ${message} ${exception:format=tostring}"/>     

The Application Log will generate upon start.  


Request Log

The third target with the name "requestFile" outputs the Request log. By default, this log is stored in the same directory as the SystemWeaver REST API executable with the file name "SystemWeaver.RestAPi.Request.log", as defined in the fileName attribute. To change the location of the log file, choose another destination and file name and enter that value in the fileName attribute, in the same way as for the Application log example above.

<target name="requestFile" type="File" fileName="SystemWeaver.RestApi.Request.log" layout="${longdate} ${message}"/>    

The Request log generates upon receiving the first request. You can test this by entering the following in a browser:


Example: 

http://localhost:9000/restapi/ping


And, then verifying the log:


Configuring the Logging Rules

There are two logging rules defined for the SystemWeaver REST API Server, one that applies to the Request logging, name= "SystemWeaver.RestApi.WebService.Setup.RequestLogger" and one that applies to Application logging, name="*". The logger rules are used to define the lowest log levels that are to be logged. For more information about log levels, see: NLog Log Levels.

 <rules> 
<logger name="SystemWeaver.RestApi.WebService.Setup.RequestLogger" minlevel="Debug" writeTo="console,requestFile" final="true"/>
<logger name="*" minlevel="Debug" writeTo="console,file"/>
</rules>

Request Log Rule

The Request log only outputs information on log level "Info". To disable it, set minLevel to "Off" or "Warning".


Application Log Rule

For the Application Log rule, it is recommended to keep the default settings.


For more information about how to configure NLog, see Nlog Configuration file.


Version R35 or Later

You will find the same logging and rules options described above in the appsettings.json file for version R35 or later. Note By default, the log files will generate in the same location as the Rest API executable unless a file path is provided, e.g., C:/Logs/SystemWeaver.RestApi.log


Example Application Log Configuration

... 
"NLog": { 
      ...
      "file": {
        "type": "File",
        "fileName": "${basedir:fixtempdir=true}/SystemWeaver.RestApi.log",
        "layout": "${longdate} ${message} ${exception:format=tostring}"  
      },
...   

Example Request Log Configuration

... 
      "requestFile": { 
        "type": " File",
        "fileName": "${basedir:fixtempdir=true}/SystemWeaver.RestApi.Request.log", 
        "layout": "${longdate} ${message}"
      }, 
...     

Logging Rules

Request Log Rule

   ...   
    "rules": [
      {
        "logger": "SystemWeaver.RestApi.WebService.Setup.RequestLogger",
        "minlevel": "Debug",
        "writeTo": "requestFile,requestConsole",
        "final": true
      },  
...    

Application Log Rule

... 
      {
        "logger": "*",
        "minlevel": "Debug",
        "writeTo": "file,console"
      } 
...    



What's Next?

See Getting Started with the SystemWeaver REST API.