GSD REST API Installation

The REST API is available to download from a gsd-restapi folder.

Requirements

DOCUframe

  • Remote Access Server (GSD Fernzugriff-Server)
  • openssl
  • GSD-MDM

DOCUframe Configuration

For proper functioning it is required to:

  • Have DOCUframe in the minimum version 5.9.4.53.
  • Import the GSD-RestApi module.
  • Change in the DOCUframe path (xRestAPI_TempPath field) to the Temp folder in the place shown in the picture below.

  • Configure GSD-MDM. Of how to do it, it can be found here.

    Screenshot

    In this temporary folder files are saved, when are downloaded from DOCUframe and when are uploaded to DOCUframe. Paths to the Temp folder in DOCUframe and api-config.json do not have to be identical (can be mapped), but must point to the same place. For exmaple:

  • \\172.11.17.60\Temp

  • ‪C:\Windows\Temp

Web Service Configuration

To start the Web Service you must run the net-api.exe file. By the first start it will create api-config.yml file. The necessary configuration of the configuration file is possible in any text editor. After the second start of net-api.exe file, the Web Service will start normally.

Using quotes in config values

We recommend to miss quotes or use single quotes in config values, because those values are not interpreted. According to YAML specification, values which are surrounded with double quotes are interpreted, so it can cause errors during reading config values.

In the api-config.yml file: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
name: RestAPI
uploadFileStoreTimeInSeconds: 5
databases:
    -
        rasServer: 127.0.0.1
        rasServerPorts:
            - 54332
        databaseServer: 127.0.0.1    
        databaseName: 'C:\testFolder\testDB'  
        databaseAlias: test  
        userName: GSDWebService
        userPassword: ""
        # Both tmpDir and docuframeTmpDir must point to the same directory.
        tmpDir: '\\GSD-SAMBA-SRV\dfTmp' # directory where REST-Api tries to get the files. May be relative path or network share. 
        docuframeTmpDir: 'C:\dfTmp' # optional absolute local path where DOCUframe should store files for REST-Api. 
        oAuthProviders: # Array of enabled oauth providers. More info under https://docs.gsd.pl/restapi/oAuth/overview/
            -
                name: Facebook
            -
                name: Google 
            -
                name: WindowsLive
        parameters: {} # additional parameters that can be passed to DOCUframe and later use in event macro 'xRestApi_SetSessionParameters' 

session:
    sessionTimeoutInSeconds: 900
    sessionRefreshInSeconds: 450
    maxSessionLoad: 10
    pool:
        driver: memory
        memory: {}
        redis:    
            host: 127.0.0.1
            port: 6379
            primaryDb: 0    
            secondaryDb: 1
listeners:
    -
        type: HttpListener
        enabled: false
        port: 8080
    -
        type: Http2Listener
        enabled: false
        port: 8335
        serverKey: cert/key.pem
        serverCert: cert/cert.pem
    -
        type: HttpsListener
        enabled: true
        port: 8334
        serverKey: cert/key.pem
        serverCert: cert/cert.pem
encryption:
    enabled: true
    salt: ""
    publicKey: ./cert/encryption-pub.pem
    privateKey: ./cert/encryption.pem
connection:
    acquireTimeoutMilliseconds: 10000
    idleTimeoutMilliseconds: 10000
    minimum: 0
    maximum: 10
logger:
    trimLogs: false
    maximumLogCharacters: 1000
    ansiColoring: true
statistics:
    enabled: false
messageBus:
    driver: memory
    memory: {}
    rabbitMQ:
        host: 127.0.0.1
        port: 5672
        userName: admin
        password: password
requestQueue:
    enabled: false
    parallelRequestCount: 5
    allowedQueueLength: -1
sync:
    enabled: false
    host: localhost
    port: 5432
    userName: postgres
    password: ""
    restApiAlias: restapi
    logging: false
    connection:
        acquireTimeoutMilliseconds: 10000
        idleTimeoutMilliseconds: 10000
        minimum: 0
        maximum: 10

You can find fully detailed field description under 'REST API/Information/Configuration/' page.


Connecting to more than one database

In order to connect with more than one database, you should configure additional database entries in `databases` array. Requests for such a database depend on the alias, for example alias will be "test1" and request - `http://127.0.0.1:8080/test1/api/v1/login` instead of default database request - `http://127.0.0.1:8080/api/v1/login` where the alias is empty. 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
name: RestAPI
uploadFileStoreTimeInSeconds: 5
databases:
    -
        rasServer: 127.0.0.1
        rasServerPorts:
            - 54332
        databaseServer: 127.0.0.1
        databaseName: 'C:\testFolder\testDB1'
        databaseAlias: test1
        userName: GSDWebService
        userPassword: 5a105e8b9d40e1329780d62ea2265d8a
        tmpDir: \\127.0.0.1\dfTmp
        docuframeTmpDir: C:\dfTmp\
        parameters: {}
    -
        rasServer: 127.0.0.1
        rasServerPorts:
            - 54332
        databaseServer: 127.0.0.1
        databaseName: 'C:\testFolder\testDB2'
        databaseAlias: test2
        userName: GSDWebService
        userPassword: ad0234829205b9033196ba818f7a872b
        tmpDir: \\127.0.0.1\dfTmp
        docuframeTmpDir: C:\dfTmp\
        parameters: {}

Linux Installation

To install and run web services on linux machines follow the steps below.

  1. Download the web service from the FTP server and extract them to the directory of your choosing.
  2. Change ownership of the extracted directory
    chown -R {name of the user}:{name of the group} {service directory}
  3. Add permission to execute specific web service chmod +x {name of the executable}
  4. Running the service - navigate to the directory containing the service and run the executable file from the terminal - ./{service executable} - this will start a configuration wizard where you will be able to configure your service.You can check and edit your configuration using text editor of your choosing.

Configuration file

Some of the services like GSD-Proxy-Server do not use the configuration wizard. If this is the case you have to create your configuration file manually. The file should be as follows {service name}-service-config.yml You can find configuration options in the documentation of each service under Web > {service} > Informations > Configuration and Web > {service} > Informations > Installation

  1. After configuration step run the executable file once again to start the service.

Verifying if the service is running

You can verify that the service is running by visiting localhost:{port}/_CheckService

Running as a service

Running as a service

To run as a service follow the linux installation steps first.

Navigate to /etc/systemd/system and create service unit file that will store the configuration. The service configuration file should end with .service.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[Unit]
Description=GSDxRESTApi service
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=www-data
WorkingDirectory={directory of your service}
ExecStart={path to service executable file}

[Install]
WantedBy=multi-user.target

For more information about systemd unit files visit this tutorial.

  • To start the service immediately run systemctl start {name of the service}.service
  • To enable the service at next reboot run systemctl enable {name of the service}.service

Service startup

The OpenSSL is required for the Web Service to work properly. Download and Install OpenSSL for Windows before starting Web Service.

Windows

Since version 2.2.6

To run application as a service, we need to run run.service.bat as administrator and answer for questions:
Do you want send statistic to GSD?[Y/N] - If you agree for sending statistic to GSD, we will be able to get better diagnostic information about possible WebService's problems and update licenses automatically.
Enter the service identifier [GSD-service-name(-yourId)] - If you want run more than one service on the system, you must add a unique ID for everyone. [default=GSD-service-name]

To version 2.2.5 or older

To run Web Service as a service, it is necessary to use external software. Recommended software is Non-Sucking Service Manager. To install the service, you need to go to the folder where the software NSSM is installed. Then hold down the CTRL+Shift keys, use mouse right click and from the context menu select position „Open command window here”. In the command window that opens, type the following command:

1
$ nssm install <service name>

Confirm by clicking the Enter button. This command opens the service editor dialog shown below:

Screenshot

In the editor dialog, you need to fill the path to the application that runs the project. The application name is net-api.exe. The second field is the path to the folder with net-api.exe file. The last field is the service name. Other settings should remain by the default. To install this configured service click „Install service” button.

Linux/MacOS

If you need to run our Node.js applications in background we recommend using supervisor. It is a simple python application which allows to easily run applications as a service. You can install it either via apt-get [debian distro] yum [redhat] or brew [macos]. However it is also possible to install it from pip which is a package manager common for each of the systems listed above.

Supervisor configuration.

After you install supervisor you should be able to run supervisorctl. If it fails you must run it as a service, depending on your system you should use either sudo systemctl start supervisord [Linux] or register the application with in launchctl via LaunchDaemon [macos].

When you have a supervisor service installed you must create configuration files for each application you wish to run in background.

Supervisor's application configuration.

Configuring supervisor to run a specific application in the background requires a configuration file per service. It is a good idea to create single configuration file per application.

Info

Please replace all occurrences of $APP_PATH in the configuration below if you wish to copy it. In this example $APP_PATH = '/opt/linux-net-api'

Security first!

Please remember to create a new user and group for your applications. You can also use www-data which is a common Debian based distros user/group for web applications. Don't forget to set a proper permissions for the $APP_PATH! 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[program:restapi]
directory=$APP_PATH
command=$APP_PATH/net-api --config "$APP_PATH/api-config.yml"
user=www-data
redirect_stderr=false
autorestart=unexpected
startretries=3
stdout_logfile=/opt/linux-net-api/log/%(program_name).log
stdout_logfile_maxbytes=100MB
stdout_logfile_backups=10
stdout_capture_maxbytes=1MB
stderr_logfile=/opt/linux-net-api/log/%(program_name)-err.log
stderr_logfile_maxbytes=100MB
stderr_logfile_backups=10
stderr_capture_maxbytes=1MB

Each of the configuration files must end with .conf and has to be placed depending on your distribution. It is defined in the /etc/supervisord.conf or /etc/supervisor/supervisor.conf under '[include]' directive.

Let's save above configuration under /etc/supervisor/conf.d/restapi.conf. In order to make it visible for the supervisor we need to reread configuration files. To do so run supervisorctl and then in the supervisor console run reread. You should be able to see restapi service. You can start it via start restapi. You can also manage the runtime using restart restapi, stop restapi, status restapi.