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


Prerequisites

  • A SystemWeaver server 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


Configuring the REST API

The top section of the appsettings.json configuration file contains the configuration information required for the SystemWeaver REST API server to be set up properly. 

Open the file with a text editor such as Notepad or Notepad++.


Example

{
  "SystemWeaver": {
    "restApiBaseURL": "localhost",
    "restApiPort": 9000,
    "requireHttps": false,
    "certificateSubjectName": "localhost",
    "systemWeaverHost": "localhost",
    "systemWeaverPort": 8888,
    "allowHttp2": true,
    "DomainName": "SYSTEMITE"   
  },
...
...
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.

DomainName: Required for use of Windows authentication only. It can be left blank if Windows authentication will not be used. Enter the organization's domain name in capital letters.


Important Note about Https

For production environment, RequireHttps=true 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. 
  • In addition in cases where a so-called self-signed certificate is used, it must be trusted. If the certificate is not part of a chain, this is achieved by copying the certificate from  Personal (My) folder to the Trusted Root Certification Authorities. 
  • If the certificate is part of a chain, the overlying certificates should be copied into the Root Certification Authorities. 
  • From a SystemWeaver perspective, it does not matter if it is an internal or external certification authority. 
  • For the RestApiBaseUrl setting, the value must be either 127.0.0.1 or a FQDN that translates to 127.0.0.1. It does not work to use "localhost" when using Https.
{
  "SystemWeaver": {
    "restApiBaseURL": "127.0.0.1",
    "restApiPort": 443,
    "requireHttps": true,
    "certificateSubjectName": "*.systemweaver.local",
    "systemWeaverHost": "localhost",
    "systemWeaverPort": 1768,
    "allowHttp2": false,
    "DomainName": "SYSTEMITE"   
  },
...

Configuring REST API 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 file called appsettings.json, there is a section called NLog. This section contains the configuration information required for SystemWeaver REST API server logging to be set up properly. Each target in the configuration represents a different log output. The main logs are described below. 


Console Logging

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

This target is not intended to be changed. 


Application Log

The second target named "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 fileName. 

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

The Application Log will generate upon start.  

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

Request Log

The third target named "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 fileName. To change the location of the log file, choose another destination and file name and enter that value in fileName, in the same way as for the Application log example above. The Request log generates upon receiving the first request. 

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

Configuring the Logging Rules

There are two logging rules defined for the SystemWeaver REST API, 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.


Request Log Rule

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

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

Application Log Rule

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

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

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

Testing the Configuration

Prior to running the Rest API as a Windows server, we recommend that you test running the executable directly. For error messages, see Troubleshooting the REST API.


Successful Application Start Example


Logs

The application and response logs will appear as shown below. 


With "requireHttps": true

With "requireHttps": false


Viewing the Documentation

The Rest API documentation can be accessed via a web browser from {url}/documentation. Test viewing the documentation. Note that Internet Explorer is not supported by Swagger UI which is used for the documentation.



Examples:   

https://localhost:8000/documentation/ for "requireHttps": true

http://localhost:8000/documentation/ for "requireHttps": false


The request should appear in the Request log as shown below.


Pinging the Rest API

Test the configuration by pinging the Rest API. You can test this in a browser by entering {url}/restapi/ping


Examples: 

https://localhost:8000/restapi/ping for "requireHttps": true

http://localhost:8000/restapi/ping for "requireHttps": false


The request should appear in the Request log as shown below.


Retrieving an Item

Test authenticating and retrieving an item. See Getting Started with the SystemWeaver REST API.