Keystone REST Server (KServer): Difference between revisions

From KeystoneIntranet
Jump to navigation Jump to search
 
m (1 revision imported)
 

Latest revision as of 12:58, 14 July 2023


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

KServer REST APIs

KServer supports several REST APIs:

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.

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: 

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()))" }
        ]
      }
    ]
  }
}

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

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

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

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

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

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)
    ]
  }
}

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

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'))" }
        ]
      }
    ]
  }
}


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: 

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()))" }
        ]
      }
    ]
  }
}


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

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

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:
kserver_win_service /install
kserver_win_service /install 8212
  • 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: 

kserver_win_service /uninstall
kserver_win_service /uninstall 8212
Retrieved from "http://in.compucrete.com/index.php?title=Keystone_REST_Server_(KServer)&oldid=396"