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
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

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

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
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: ""
        tmpDir: C:\tmp\
        docuframeTmpDir: C:\dfTmp\
    -
        rasServer: 127.0.0.1
        rasServerPorts:
            - 54332
        databaseServer: 127.0.0.1
        databaseName: 'C:\testFolder\testDB2'
        databaseAlias: test2
        userName: GSDWebService
        userPassword: ""
        tmpDir: C:\tmp\
        docuframeTmpDir: C:\dfTmp\

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.