Configuration
Changes from 2.1
There are no major changes regarding configuration since 2.1.
We have added new session refresh mechanism and you can configure it under:
session.sessionRefreshInSeconds
Also OAuth support under: database.oAuthProviders
Configuration wizard
One of the possible options for configuring our services is to use our configuration wizard. It make basic configuration easier.
Net-Api v2.2
name:
Application identifier. May be used in logs.
uploadFileStoreTimeInSeconds:
Time after the file will be deleted after the upload.
httpSocketTimeoutMilliseconds
[Since 2.2.38] Sets the timeout of HTTP, HTTPS and HTTP/2 request. If a DOCUframe macro takes longer to serve your request then you should adjust this value.
parallelDBOpen [boolean]:
[Since 2.2.6] If true, all databases will register simultaneously. If false application will register DBs one after another.
publishService [boolean]:
[Since 2.2.23] Bonjour / Zeroconf protocol. The service type is 'GSDRestApi'. For information's how to set up your module to be broadcast go to module events
databases [array]:
rasServer:
IP of the RAS (Remote Access Server) to which you wish to connect.
rasServerPorts [array]:
Array of ports the RAS is listening. When you have multiple ports then the first to respond will handle your request.
databaseServer:
IP of the Database Server.
databaseName:
Path or alias of the database.
databaseAlias:
Allows to run single REST-Api with multiple databases. Each database must have its own unique alias. For more information please check the "Connecting to more than one database" on REST API/Information/Installation page.
Alias 'v1' and 'v2' are not permitted to avoid naming conflicts.
userName:
Username which will init the connection.
userPassword:
MD5 hash of the user's web password.
tmpDir:
Absolute/Relative path where REST-Api should store/look for files from DOCUframe
docuframeTmpDir (optional):
Absolute path where DOCUframe will store/fetch files. If not set then DF will get path from its config. Allows to use multiple REST-Api databases while having single DOCUframe application without file overlapping.
tmpDir and docuframeTmpDir must point to the exact catalog
If your DF is on another server then you must mount docuframeTmpDir to the tmpDir in order to be able to upload/download files.
oAuthProviders [array]:
[Since 2.2.0] OAuth providers name configuration
More info under oAuth configuration
name
Name of the provider configuration in DOCUframe. This corresponds to provider configuration object which holds secret keys.
session:
sessionTimeoutInSeconds:
Time after the session becomes invalid.
sessionRefreshInSeconds
[Since 2.2.0] Specifies time in seconds after which net-api should make session refresh to license server. This is critical setting if net-api's session timeout is bigger than license server and may be ignored otherwise.
Tip
Must be bigger than session timeout in GSD Licenz Server.
maxSessionLoad:
Maximum amount of request that single session can make.
pool:
driver:
Tells which driver should handle session storage. Using memory will allow users to connect only to the single instance of this app. This means that if you have two application running then you must log to each separately.
redis:
host:
IP address of redis application.
port:
Redis port.
primaryDb:
Primary database which stores user sessions.
secondaryDb:
Secondary database which stores generic application data.
memory:
Setting's placeholder. May be used in future.
listeners [array]:
Listeners on which application will wait for client's requests.
HTTP2 and HTTPS require keys and certificates.
Keep in mind that you should always use your own certificate. The ones bundled with the app do not guarantee maximum security and should only be used in non-production environments.
encryption:
Enables second layer of encryption. Application was tested with PKCS 1 or 8 key standard.
publicKey:
Path to public key. Will be generated if does not exists.
privateKey:
Path to private key. Will be generated if does not exists.
salt:
String of random characters.
This option makes your AES keys much more secure and cryptographically safe.
Info
It is advised to set this configuration by typing random string directly from your keyboard.
enabled:
Enables secure routes registration. If disabled then keys will not generate.
connection:
acquireTimeoutMilliseconds:
Time after client will be timed out. It will work when the number of current connections is equal to maximum connections allowed.
idleTimeoutMilliseconds:
The time after connection socket will be disconnected and removed.
minimum:
Minimum number of connections that stay available for clients.
maximum:
Maximum number of simultaneous connection to DOCUframe.
logger:
trimLogs:
Turn on if you want to trim part of logs.
maximumLogCharacters:
Number of characters from the begging you want to preserve in a console when trimLogs is enabled.
ansiColoring:
Enables log coloring. If your logs do not color and contain strange characters then turn this option off.
This feature requires an ANSI support in console.
It is enabled by default on Windows 10 and Unix. Older operating systems do not support it.
logToGSDMonitor [boolean]:
[Since 2.2.11] Enables logging to GSD Monitor
statistics:
enabled:
Enables statistics logging.
More information can be found here
messageBus:
driver:
Tells which driver should handle messaging between rest-api instances. Using memory will allow users to connect only to the single instance of this app. This means that if you scaling rest-api horizontally you must use rabbitMQ otherwise rest-api may work unstable.
rabbitMQ:
host:
IP address of rabbitMQ application.
port:
RabbitMQ port.
userName:
RabbitMQ username.
password:
RabbitMQ password.
requestQueue
Warning
Request queue is strictly related to TCP connection persistence. If you want to enable request queue make sure that you handle your connections properly. This means using the same TCP connection for many request and/or proper closing of those TCP connections. Unclosed and unused TCP connections may result in request queue saturation. For instance, when request queue is enabled and parallelRequestCount set to 5, there can only be 5 simultaneously open TCP connections. Request made from another TCP connection won't be processed until close or timeout of previous ones.
[Since 2.2.7] Request queue allows to threshold maximum parallel connection to the backend. The difference between queue and the connection pool is that it does not have "acquire" timeout and only one instance of queue is used for the entire application while connection pool is created per database alias.
enabled
Enables the queue
parallelRequestCount
Maximum simultaneous requests.
allowedQueueLength
This value allows to specify how long the queue can get. Default is -1 for no limit. Returns 204
sync
Warning
When synchronization is enabled in module configuration should be launched a data exchange macro xRestApiMoveDeletedOids.
[Since 2.2.15] Synchronization of Docuframe database objects with the PostgreSQL database.
enabled
Enables the synchronization.
host
IP address of synchronization database.
port
Port where synchronization database is running.
userName
User name for synchronization database user.
password
Password for synchronization database user.
restApiAlias
Alias for synchronization database.
logging
Possibility to enable/disable logging sql queries at console.
connection:
Separated connection pool for synchronization.
acquireTimeoutMilliseconds:
Time after client will be timed out. It will work when the number of current connections is equal to maximum connections allowed.
idleTimeoutMilliseconds:
The time after connection socket will be disconnected and removed.
minimum:
Minimum number of connections that stay available for clients.
maximum:
Minimum number of connections that stay available for clients.
checkService:
Endpoint to check the service status
enabled:
Enables the checkService.