WikiAdmin: 1 revision imported

2023-07-14T12:58:52Z

1 revision imported

← Older revision

Revision as of 12:58, 14 July 2023

Chanson: /* KServer REST APIs */

2023-05-09T14:05:25Z

KServer REST APIs

New page

[[CATEGORY: KSERVER]]

==Introduction==

The Keystone REST Server (KServer for short) is a general-purpose REST server designed to interface with the Keystone mobile apps, Keystone customer portal and third-party applications.

KServer is a configurable server that uses JSON text files to define its functionality. These files are documented [[KServer_JSON_Files|here]].

==KServer REST APIs==

KServer supports several REST APIs:
*[[KServer REST API]] (Server version and statistics)
*[[KServer JSON Files]] Includes KServer '''Functions'''
*[[Keystone Mobile Server REST API]] (deprecated Keystone On-Demand App)
*[[Keystone Customer Portal REST API]] (deprecated)
*[[Keystone Customer Portal REST API Ver. 2]] ("kcpapi")
*[[Keystone GPS Rest API]] ("kgpsapi")
*[[Keystone Driver App REST API]] (Keystone On-Delivery - "ktrapi")
*[[Keystone Batch Control Quality Control Interface REST API]] (Stonemont QC - "kbcqciapi1")
*[[Keystone Quote REST API]] (Keystone Quoting - "kqtapi1")
*[[Keystone Dispatch REST API]] (Keystone Dispatch - "kdiapi")
*[[Keystone FX REST API]] (KPI Dashboards - "kfxapi")
*[[Keystone Online Customer Portal REST API]] (Keystone Online - "kOLcpapi")
*[[Keystone Online E-Ticketing REST API]] ("kOLetapi")
*[[Keystone Online Reports API Ver. 1]] ("kOLrepapi")
*[[Keystone Windows Client System Database REST API]] (Keystone Windows Client)
*[[Keystone Windows Client Company Database REST API]] (Keystone Windows Client)

==KServer Reports==

As of version 3.6.31 KServer supports defining reports in the JSON configuration files. These reports are printed on the client side using a single generic report program.

*[[KServer Report JSON Syntax]]
*[[Sample KServer Reports]]

==Customer-Specific Endpoints==

As of version 3.4.5.5 KServer supports customer-specific endpoints. New endpoints can be added and existing "standard" endpoints can be replaced.

At startup, KServer first processes .json files in the "C:\ProgramData\GivenHansco\Keystone\Settings" (customer-specific) folder. It then processes .json files in the "C:\Program Files (x86)\GivenHansco\Keystone\Bin" (master) folder. In this way, existing standard endpoints that are defined in the customer-specific folder replace their counterparts in the master folder.

===Adding Endpoints===

KServer attempts to load the "kserver_custom.json" file at startup. This optional file is used to define new customer-specific endpoints.

Here is an example customer-specific JSON file that adds a new “/rest/custom/version” endpoint:

<pre>
File: C:\ProgramData\GivenHansco\Keystone\Settings\kserver_custom.json

{ "ghJSONMapper": {
"id": "kserver_custom",
"URI": "/custom",
"endpoints": [
{ "URI": "/version",
"actions": [
{ "type": "before", "name": "JSON(Format('\"%s %s\"', 'kserver', ServerVersion()))" }
]
}
]
}
}
</pre>

Suppose that several new customer-specific APIs are needed. First we want to define an endpoint to return a customized server version string:

<pre>
Request: GET http://127.0.0.1:8211/rest/custom/server/version
Response: "kserver 3.4.5.5"
</pre>

Next we want to define an endpoint to return a customized status for the caching system:

<pre>
Request: GET http://127.0.0.1:8211/rest/custom/status/cache
Response: "OK"
</pre>

First you define the "kserver_custom.json" file to point to the other map files as follows:

<pre>
File: C:\ProgramData\GivenHansco\Keystone\Settings\kserver_custom.json

{ "ghJSONMapper": {
"id": "kserver_custom",
"URI": "/custom",
"maps": [
"kserver_custom_version",
"kserver_custom_status",
… (as many as you need)
]
}
}
</pre>

Then define the remaining customer-specific JSON files as follows:

<pre>
File: C:\ProgramData\GivenHansco\Keystone\Settings\kserver_custom_version.json

{ "ghJSONMapper": {
"id": "kserver_custom_version",
"URI": "/server",
"endpoints": [
{ "URI": "/version",
"actions": [
{ "type": "before", "name": "JSON(Format('\"%s %s\"', 'kserver', ServerVersion()))" }
]
}
]
}
}

File: C:\ProgramData\GivenHansco\Keystone\Settings\kserver_custom_status.json

{ "ghJSONMapper": {
"id": "kserver_custom_status",
"URI": "/status",
"endpoints": [
{ "URI": "/cache",
"actions": [
{ "type": "before", "name": "JSON(Format('\"%s\"', 'OK'))" }
]
}
]
}
}
</pre>

===Replacing Standard Endpoints===

When KServer loads the various .json files, it first attempts to load the file from the customer-specific folder, then from the master folder. In this way standard endpoints can be replaced.

Here is an example customer-specific JSON that changes the standard “/rest/kserver/version” endpoint to return a different value:

<pre>
File: C:\ProgramData\GivenHansco\Keystone\Settings\kserver_version.json

{ "ghJSONMapper": {
"id": "kserver_custom",
"URI": "/kserver",
"endpoints": [
{ "URI": "/version",
"actions": [
{ "type": "before", "name": "JSON(Format('\"%s %s\"', 'kserver', ServerVersion()))" }
]
}
]
}
}
</pre>

==Configuration==

KServer uses an INI file (kserver.ini) to read configuration information. This file should be placed in the Keystone system-wide settings folder (C:\ProgramData\GivenHansco\Keystone\Settings.)

As of Keystone 3.2, the kserver.ini file is optional if the following conditions are met:
* Keystone is installed on the same PC as KServer
* KServer will access data from the company 001 database
* KServer will be running on a single port (8211)

Note that any time this configuration file is changed, all instances of KServer must be restarted for the changes to take effect.

===Sample kserver.ini===

<pre>
[config]
ports=8211,8212
mappath=C:\Program Files (x86)\GivenHansco\Keystone\Bin
logpath=C:\Users\<user>\Documents\GivenHansco\Keystone\Log
loglevels=9
logevents=SERVER,ERROR
LicenseType=2
UseCompression=True
QuietMode=True
DBco=DriverID=IB;Server=127.0.0.1;Protocol=TCPIP;Database=C:\CCGH\Data\ccw001.ib;User_name=CCWIN;Password=<password>
DBsys=DriverID=IB;Server=127.0.0.1;Protocol=TCPIP;Database=C:\CCGH\Data\ccwsys.ib;User_name=CCWIN;Password=<password>
[config_8212]
mappath=C:\Program Files (x86)\GivenHansco\Keystone\Bin
logpath=D:\KServerLogs
loglevels=9
logevents=SERVER,QUERY,ERROR
LicenseType=2
UseCompression=True
QuietMode=True
DBco=DriverID=IB;Server=127.0.0.1;Protocol=TCPIP;Database=C:\CCGH\Data\ccw002.ib;User_name=CCWIN;Password=<password>
DBsys=DriverID=IB;Server=127.0.0.1;Protocol=TCPIP;Database=C:\CCGH\Data\ccwsys.ib;User_name=CCWIN;Password=<password>
</pre>

===Configuration file parameters===

Each [config_xxxx] section contains the configuration for one instance of the REST server running on a specific port (where xxxx is the port number, 8211 is the default.) Defaults are shown in square brackets [].

AuthRequired [False]
:whether to require JWT authorization within the server if specified in the .json file (disable when diagnosing with a web browser)

CacheLockRetries [3]
:number of times to retry when loading cache version keys

CoID [001]
:company ID for the company database to be used by KServer

ConnRetries [3]
:number of times to retry opening database connections

DBco [DriverID=IB;Server=[DBServer];Protocol=TCPIP;Database=[DBPath][PathDelim]ccw[CoID].ib;User_name=[DBUserName];Password=[DBPassword]]
:Database-specific driver information for the company database that applies to this REST server instance as follows:
::DriverID = the database engine (IB for InterBase)
::Server = the IP address of the database server
::Protocol = the protocol to connect to the database server
::Database = the path to the database file on the database server
::User_name = the user name to login to the database server
::Password = the password to login to the database server

DBco### [DriverID=IB;Server=[DBServer];Protocol=TCPIP;Database=[DBPath][PathDelim]ccw###.ib;User_name=[DBUserName];Password=[DBPassword]]
:Database-specific driver information for the company ### database that applies to this REST server instance (see DBco)

DBdoc [DriverID=IB;Server=[DBServer];Protocol=TCPIP;Database=[DBPath][PathDelim]ccwdoc.ib;User_name=[DBUserName];Password=[DBPassword]]
:Database-specific driver information for the document imaging database that applies to this REST server instance (see DBco)

DBlocal [DriverID=SQLite]
:Database-specific driver information for local queries that applies to this REST server instance

DBPassword [default provided by KServer]
:password for database server

DBPath [from Keystone ccwibcp.ini IBClientParams->Database Path]
:path to the database files on the database server

DBServer [from Keystone ccwibcp.ini IBClientParams->Server Name]
:IP address of the database server

DBsys [DriverID=IB;Server=[DBServer];Protocol=TCPIP;Database=[DBPath][PathDelim]ccwsys.ib;User_name=[DBUserName];Password=[DBPassword]]
:Database-specific driver information for the system database that applies to this REST server instance (see DBco)

DBUserName [default provided by KServer]
:user name for database server

DBVendorHome [(blank)]
:specify folder containing vendor-specific database library
::<default> = use default operating system path
::(blank) = use vendor-specific default path

DefRequestThreads [0]
:specifies the default number of HTTP request threads (can be overridden with RequestThreads option)

DocType_BatchWeight [2]
:Document Type to be used when recording batch weight document (see DOCTYPE_ID in DOTDOCTYPE table)

DocType_Ticket [1]
:Document Type to be used when recording ticket document (see DOCTYPE_ID in DOTDOCTYPE table)

IgnoreAutoRun [False]
:whether to ignore all endpoints where the "autorun" property is True

IgnoreCached [False]
:whether to ignore the cached setting for specific queries within the .json file

IgnoreListEndPoints [False]
:whether to ignore the "ListEndPoints" action

IgnoreLocalCached [False]
:whether to ignore the cached setting for specific LOCAL queries within the .json file

IPAllowed [(all)]
:comma-delimited list of allowed client IP addresses

LicenseType
:the Keystone license type (1 = Demo, 2 = StandAlone, 3 = Network Server, 4 = Network Workstation)

logevents [SERVER,ERROR]
:the events that should be stored in the log file (comma-separated) as follows:
::ERROR = server exceptions
::MONITOR = FireDAC DB Monitor (extremely detailed)
::PARAM = (unused)
::QUERY = queries that are run
::REQUEST = server REST requests (truncated)
::REQUESTFULL = server REST requests (full) -- must include REQUEST
::REQUESTRAW = server REST requests (raw form)
::RESPONSE = server REST responses (truncated)
::RESPONSEFULL = server REST responses (full) -- must include RESPONSE
::SECURITY = server security failures
::SERVER = major server events
::TRACE = other detailed information

loglevels [30]
:the maximum number of log files that should be stored

logpath [C:\ProgramData\GivenHansco\Keystone\Log]
:the folder where the REST server log files should be stored

logsize [50000]
:the maximum number of lines in a single log file

MapAllowed [(all)]
:comma-delimited list of allowed API map Ids

mapcustompath [C:\ProgramData\GivenHansco\Keystone\Settings]
:the folder containing the .json files that describe the customer-specific REST server functionality

mappath [C:\Program Files (x86)\GivenHansco\Keystone\Bin]
:the folder containing the .json files that describe the REST server functionality

PathDelim ["\" for Windows, "/" for Linux]
:path delimiter

ports [8211]
:a list of IP ports (separated by commas) that KServer will listen on (requires Keystone 3.2.8 or higher)

QuietMode [True]
:True returns 404 errors only for requested resources that are "close" to an existing resource (discourages hacking attempts)
:False returns 404 errors for all invalid resources (useful for diagnosing)

RequestThreads [DefRequestThreads]
:allows override of the number of HTTP request threads

SysId [from Keystone ccwibsv.ini Telemetry->SysId]
:specifies the System Id of Keystone for telemetry purposes

UseCompression [True]
:whether to use compression when returning data from the server (disable when diagnosing with a web browser)

==Installing the Windows Service==

NOTE: As of Keystone 3.2.8 you can use the "ports" option in kserver.ini to support multiple IP ports instead of using this procedure.

The kserver_win_service.exe Windows Service must be installed once for each instance you want to run.

===Install===

*Open a Command Prompt selecting Run As Administrator.
*Change to the folder containing the kserver_win_service.exe process (usually C:\Program Files (x86)\GivenHansco\Keystone\Bin.)
*Issue the commands to install the service. Here is an example of installing two instances of KServer on ports 8211 & 8212:

<pre>
kserver_win_service /install
kserver_win_service /install 8212
</pre>

*Start the service(s) using the Administrative Tools->Services control panel applet.

===Uninstall===

If you need to uninstall the service, the commands are similar to the install service commands:

<pre>
kserver_win_service /uninstall
kserver_win_service /uninstall 8212
</pre>

Keystone REST Server (KServer) - Revision history

WikiAdmin: 1 revision imported

Chanson: /* KServer REST APIs */