Data API
The Data API provides a set of tools you can use to have your APPX applications respond to web based queries.
Overview
The Data API is a collection of tools that will allow you to easily write subroutines that can respond to web based requests. It is designed to provide an interface between the APPX runtime environment and Web-based services such as a Web server or a mobile application.
Prerequisites
The Data API requires:
- A sever running nodejs 10 or higher, and a web server
- An installation of version 5.5 or higher of the APPX runtime environment
- A dedicated APPX username/password set up in the APPX runtime environment for logins
- A dedicated APPX Login Manager instance to login to the APPX runtime environment as an APPX user
Installation/Removal
First, define a new user in the APPX User file. This should NOT be an account that is also an O/S user. Assign the user a password using the 'Change Aux Password' button.
Next, unzip the 'dataservices.zip' file into the $APPXPATH/services directory.
Install the required Node JS modules (run this as root or an Administrator):
npm install --loglevel=error
Several nodejs modules will be installed
Install the APPX Data Services service instance. Replace items in <> with values of your choice, for example:
<webport> = The port you want to the API to listen on.
<portnumber> = The login manager port of your APPX server.
<appx username> = the user you defined above (not an OS user). This is the APPX user the API will log in as.
<appx password> = the password of the user defined in APPX
<appxhost> = the host name of your APPX server
<name> = The name you want to use for this service
<configuration file name> = the name of a configuration file that contains the parameters. This file is created when you remove the Data API and provides you a quick way to re-install using the previous settings
The install service command:
node servicectl.js install -p <webport> --appxhost=<hostname> --appxport=<portnumber> --appxuser=<appx username> --appxpass=<appx password>
Examples:
node servicectl.js install -p 3000 --appxhost=myhost --appxport=8161 --appxuser=Test --appxpass=password
To install from a saved configuration file:
node servicectl.js install --configfilename=default-3000.json.bak
The remove service command:
node servicectl.js remove --p=
Example:
node servicectl.js remove --p=3000
After installation a configuration file will be created in the 'config' subdirectory of the APPX Data Services directory. That configuration file is a JSON formatted file and will be named default-xxxxx.json where xxxxx is the <webport> number specified on the during installation. The configuration file is where you can change the parameters that where specified during the installation.
Also, you can change other parameters that weren’t specified during installation such as whether to use SSL and the SSL certificate file and its key file.
For example:
To specify that SSL be used on the web interface set:
"enablessl": true
in the "AppConfig" section.
To specify that SSL be used on the APPX login manager interface set:
"enablessl": true
in the "ProviderConfig" section.
To sepcify the SSL certificate and key files for Windows set:
"systemcert": "C:\\Certs\\myhost.crt",
"certificatepath": "C:\\Certs\\myhost.crt",
"privatekeypath": "C:\\Certs\\myhost.key",
and for Linux set;
"systemcert": "/opt/certs/myhost.crt",
"certificatepath": "/opt/certs/myhost.crt",
"privatekeypath": "/opt/certs/myhost.key",
in the "AppConfig" section.
After removal, the there will be a backup copy of the configuration file created in the APPX Data Services directory service with a .bak extension.
This backup copy can be used for reinstallation of a APPX Data Services instance as shown above.
Creating a Persistent Authentication Token
For faster logins you can create a persistent authentication token that can be used in place of the appxuser and appxpassword. To create that token, run the script as shown below, after substituting <username> with the actual name of the user:
node createPAT.js --username=<username>
After creating the token, copy it into the APPX login manager 'tokens' directory.
Then, in the configuration file, change the "ProviderConfig" section parameter as follows: "appxtoken": <token file name>
Next, in the "ProviderConfig" section change the following: "appxuser": "" and "appxpass": ""
Finally, stop and then restart the APPX Data Services service
Manually installing a new APPX Login Manager Service Instance
Use the command line examples below to manually create an APPX Login Manager Service instance for APPX Data Services. These commands should be executed in the APPX login manager executable directory.
Replace items in <> with values of your choice, for example:
<service name> =
AppxDSLoginManager -8161
<service display name> =
AppxDSLoginManager -8161
<portnumber> = 8161
<full path to appx engine executable> = for Linux: /opt/appxserver/appx | for Windows: c:\appx\Appx.exe
<path to the appx data directory> = for Linux: /opt/appxserver/data | for Windows: c:\appx\data
Linux:
sudo ./appxLoginMgr -install -name=<service name> -displayName="<service display name>" -SockPort=<portnumber> -engine=<full path to appx engine executable> -AuthenticationMethod=Appx-User -ImpersonateGroup=NamedGroup\(appxgrp\) -ImpersonateUser=NamedUser\(appx\) -AppxProcessName=WEBSERVICES -AppxProcessType=SUBROUTINE -AppxApplication=0LA -ServiceType=data APPXPATH=<path to the appx data directory> APPX_KEYMAP=Windows
Example:
sudo ./appxLoginMgr -install -name=AppxDSLoginManager-8161 -displayName="AppxDSLoginManager-8161" -SockPort=8161 -engine=/opt/appxserver/appx -AuthenticationMethod=Appx-User -ImpersonateGroup=NamedGroup\(appxgrp\) -ImpersonateUser=NamedUser\(appx\) -AppxProcessName=WEBSERVICES -AppxProcessType=SUBROUTINE -AppxApplication=0LA -ServiceType=data APPXPATH=/opt/appxserver/data APPX_KEYMAP=Windows
Windows:
cmd /c "appxLoginMgr.exe -install -name=<service name> -displayName=<service display name> -SockPort=<portnumber> -engine=<full path to appx engine executable> -AppxApplication=0LA -AppxExecutable=c:\appx55\Appx.exe -AppxProcessName=WEBSERVICES -AppxProcessType=SUBROUTINE -AuthenticationMethod=Appx-User -ServiceType=data APPXPATH=<path to the appx data directory> APPX_KEYMAP=Windows"
Example:
cmd /c "appxLoginMgr.exe -install -name=AppxDSLoginManager-8161 -displayName=AppxDSLoginManager-8161 -SockPort=8161 -engine=c:\appx\Appx.exe -AppxApplication=0LA -AppxExecutable=c:\appx\Appx.exe -AppxProcessName=WEBSERVICES -AppxProcessType=SUBROUTINE -AuthenticationMethod=Appx-User -ServiceType=data APPXPATH=c:\appx\data APPX_KEYMAP=
Windows"
Testing the APPX Data Services interface for connectivity
Once installed, you can test connectivity by entering the URL's below in a web browser or by using curl (Note: curl is available by default in Windows 10 since 5/2019).
To test connectivity between the browser/curl and APPX Data Services (Note: replace items in <> with the value of your host/ip):
https://<myhost>/dstest (Note: will return the value OK)
https://<myhost>/dsver (Note: will return the APPX Data Services version number in JSON format {i.e. {"Data Services Version":"1.0.0.20021010"}
})
https://<myhost>/dsdate (Note: will return the APPX Data Services service current date/time in in JSON format {i.e. {"LocalDateTime":" 02/10/202
0 15:43:31"},{"UtcDateTime":" 02/10/2020 20:43:31"} ))
Note: If you don't have SSL enabled in the "AppConfig" section remove the 's' in https
To test connectivity between the browser/curl and the APPX runtime environment via the APPX Data Services service:
https://<myhost>/api/DateTest (Note: will return the APPX runtime current date/time in in JSON format {i.e. {"DateTime":"02/10/20 15:46 04"} ))
https://<myhost>/api/GetApps (Note: will return the APPX runtime current date/time in in JSON format {i.e. {"id":"Application Design","label":"0AD 00
- Application Design","value":"0AD"},... etc, } )
Adding Your Services
-- Jean Neron - 2020-03-03
Comments