1. General


1.1. What is StoreHouse5 API?

1.1.1. SH5 provides HTTP protocol interface on its API server.

1.1.2. Server SH5WAPI2 provides ability to exchange data with SH5 DB in predefined StoreHouse5 JSON (www.json.org) formatted files.

1.1.3. Communication of StoreHouse5 API server based on named procedures only, which should be identified by server.

1.2. Interface versions

1.2.1. current API version is 1.6.

1.2.2. previous versions supported less operations


2. Requests


2.1. There are several possible operations available:

2.1.1. Get datasets list for some procedure: /api/sh5struct

2.1.2. Execute some procedure: /api/sh5exec

2.1.3. Get server settings and DB info: /api/sh5info

2.1.4. Get user rights for procedure execution: /api/sh5able

2.1.5. Change user password: /api/sh5pass

2.1.6. Get license information: /api/sh5lic

2.2. Request format and protocol

2.2.1. Use HTTP POST query (protocol).

2.2.2. Request must be sent to SH5 server address and port.

2.2.2.1. You may use domain name with DNS resolution.

2.2.3. Request content must submitted to those path ways mentioned above with Content JSON-file :

{
  "UserName": "Admin",
  "Password": "12345",
  "procName": "XDivisions"
}

2.2.3.1. Where must be 3 obligatory parameters in request:

2.2.3.1.1. UserName (string) - is user name from StoreHouse5 system.

2.2.3.1.1.1. Obligatory for all requests

2.2.3.1.2. Password (string) - is password of StoreHouse5 user

2.2.3.1.2.1. Obligatory for all requests

2.2.3.1.3. procName (string) - name of preset StoreHouse5 procedure

2.2.3.1.3.1. Obligatory for sh5exec and sh5struct requests

2.2.4. Result will be in JSON-file too. Example response:

{
"errorCode": 1, 
"errMessage": "procedure XDivisions is not found", 
"Version": "1.1", 
"UserName": "Admin", 
"actionName": "XDivisions", 
"actionType": "Structure", 
"errorInfo": { "moduleId": 1, "moduleName": "SDBCLI.DLL", "errorId": 194 }
}

2.2.4.1. Where must be 3 obligatory parameters (any response will contain them):

2.2.4.1.1. errorCode (number) - if error happened or not; possible values: 0 or 1;

2.2.4.1.2. errMessage (string) - error text;

2.2.4.1.3. Version (string) - server SH5WAPI2 version.

2.2.4.1.4. UserName (string) - same as in request

2.2.4.2. Optional parameters in successfull result (with "errorCode"=0):

2.2.4.2.1. actionName (String) - name of StoreHouse5 procedure;

2.2.4.2.2. actionType (String) -operation called: "Structure" or "Execute" ;

2.2.4.2.3. shTable (Array) - list of objecs "Table structure" or "table filled with data" ;

2.2.4.3. Optional parameters in result with error (with "errorCode"=1):

2.2.4.3.1. errorInfo (array) - information about error, including elements:

2.2.4.3.1.1. moduleId (number) -module identifier, which generated error [0..5]

2.2.4.3.1.2. moduleName (string) - module name, which generated error

2.2.4.3.1.3. errorId (number) - error code, individual for each module

2.3.  JSON files must have UTF-8 encoding.

2.4. Procedure :

2.4.1. accepts parameters: datasets (tables) ;

2.4.2. returns requested information as response.

2.5. SH5 datasets may be:

2.5.1. one line

2.5.2. multiple lines.


3. Server settings


3.1. SH5 API server may be started with the following parameters (command line):

3.1.1. /Install - install as Windows service;

3.1.2. /Uninstall - uninstall service from OS;

3.1.3. /Desktop - start as application on Windows desktop, with tray icon, where stop menu option exists;

3.1.4. /Silent - do not show information window when used one of those parameters from above;

3.1.5. /Name:SH5WAPI2 - Service and server name;

3.1.5.1. default server name is SH5WAPI2.

3.1.5.2. name defines folder path - for settings read and logs write (files of this instance).

3.1.5.2.1. Relative path to server .exe should be present named like this.

3.1.5.2.2. File CONFIG.INI will be searched for in this folder.

3.1.5.3. Service name in case /install used will be the same as server name.

3.1.6. /Port:9797 - TCP port to be used for client connections.

3.1.6.1. Default port is 9797.

3.2. Configuration file CONFIG.INI

3.2.1. Format :

LogLevel = 2
sh5tcp = 0
sh5server = SDBSERV
sh5host = 127.0.0.1 
sh5port = 7771
sh5cp = 1251
;SSL_cert = cert1.pem
;SSL_priv = priv1.pem
;SSL_psw = 
;SSL_CA =

3.2.2. description

3.2.2.1. LogLevel - level for detailed info in log file. Possible  values: 0-do not save anything; 1-basic info; 2-add Headers and Content to basic level.

3.2.2.2. sh5tcp - use of SH5 main server protocol, choice. Possible  values: 0-local protocol; 1-TCP.

3.2.2.3. sh5server - name of SH5 main server. Default: SDBSERV. Enter correct name of the server to connect to.

3.2.2.4. sh5host - SH5 main server network IP address or host name to connect with TCP

3.2.2.5. sh5port - StoreHouse5 main server TCP port

3.2.2.6. sh5cp - SH5 database codepage

3.2.2.7. SSL_cert - current server certificate filename for SSL connection.

3.2.2.7.1. No need to have this parameter for non-encrypted connection (remove line from file)

3.2.2.8. SSL_priv - private key filename for SSL connection

3.2.2.9. SSL_psw - private key password, in case it was set.

3.2.2.10. SSL_CA - certification authority filename (optional)

3.3. Server SH5 requires additional libraries in .exe folder:

3.3.1. borlndmm.dll

3.3.2. sdbcli.dll

3.3.3. domm.dll

3.3.4. dset.dll

3.3.5. cc3260.dll

3.4. Log files

3.4.1. Will be stored in subfolder LOGS

3.5. Templates

3.5.1. Will be stored in subfolder TEMPLATE

3.5.2. They are optional in JSON-format, contain alternative names for dataset fields and procedures of SH5

3.5.3. Purpose - to refer fileds with custom names, not StoreHouse5 default.

3.5.4. With optional alternative names it is still possible to use both them and original names. Both are active.

3.5.5. File with alternative fields names will come as result in case you request dataset structure for procedure, add "alt" attribute to names of desired fields. 

3.5.6. File name consist of procedure name plus "_desc.json".

3.6. For test of server work there is software Swat.exe available.


4. Get datasets


4.1. For getting datasets, list for some procedures

4.1.1. Send request to path /api/sh5struct .

4.1.2. with at least 3 obligatory parameters, mentioned above:UserName, Password, procName.

4.1.3. Get result as object array in "table structure" format. Result has elements:

4.1.3.1. UserName (string) - same use name as in request

4.1.3.2. actionName (string) - procedure name from StoreHouse5
4.1.3.3. actionType (string) - "Structure" - which requested
4.1.3.4. shTable (Array) - list of objects (elements of "table structure"), details below.

4.2. "Table structure" element in response contains the following elements:

4.2.1. head (String) - table identifier

4.2.2. SingleRow (Bool) - single line data (true) or multiple lines (false)

4.2.3. fields (Array) - list of objects "table fields"

4.2.4. Element "table fields" contains the following eleents:

4.2.4.1. path (String) - original field name

4.2.4.2. type (String) - field type

4.2.4.3. size (String) - field size

4.2.4.4. alt (String) - alernative field name (optional)

4.3. Example of successfull response:

{ 
 "errorCode": 0, "errMessage": "OK", "Version": "0.1", "actionName": "Divisions", 
 "actionType": "Structure", 
 "shTable": 
 [
  {
   "head": "103", "SingleRow": false, 
   "fields": 
   [
    {     "path": "1", "type": "tUint32", "size": 4, "alt": "Rid"    }, 
    {     "path": "4", "type": "tGuid", "size": 16, "alt": "Guid"    }, 
    {     "path": "3", "type": "tStrZ", "size": 255, "alt": "Name"    }, 
    {     "path": "7\\$Qush", "type": "tStrP", "size": 0    }, 
    {     "path": "7\\$PDocNum", "type": "tStrP", "size": 0    }, 
    {     "path": "7\\$IDocNum", "type": "tStrP", "size": 0    }, 
    {     "path": "7\\$GDocNum", "type": "tStrP", "size": 0    }, 
    {     "path": "7\\Chef", "type": "tStrP", "size": 0    }
   ]
  },  {
   "head": "103#1", "SingleRow": true,
    "fields": 
   [
    {     "path": "239", "type": "tUint32", "size": 4, "alt": "MaxCount"    }, 
    {     "path": "240", "type": "tUint32", "size": 4    }
   ]
  }
 ]
}
 

5. Execute procedures


5.1. For executing of SH5 procedures

5.1.1. Send request

5.1.1.1. to path  /api/sh5exec

5.1.1.2. Pass data to procedure with element "Input"

5.1.1.2.1. Other option for this is element "dsParams" (old version compatible). This method is deprecated.

5.1.1.2.2. "Input" (Array) contains list of objects "table data".

5.1.1.2.3. "dsParams" (Object) contains "data fields", with alternative names only .

5.1.1.2.3.1. "data fields" is an element - array with some field values of the table (all records)

5.1.1.3. Request example with simple "Input":

{
 "UserName": "Admin", "Password": "", "procName": "GDoc0", 
 "Input": 
 [
  { "head": "111", "original": [ "1" ], "values": [ [ 3 ] ] }
 ]
}

5.1.1.4. Some procedures require table record status to be passed for changing or deleting.

5.1.1.4.1. In this case need to add array "status" to element "table data" on request, where listed statuses for each record to get.

5.1.1.4.2. Possible ways: "Insert", "Modify", "Delete". Default is "Insert".

5.1.1.4.3. Example request with statuses

{
 "UserName": "Admin", "Password": "", "procName": "ModCountries", 
 "Input": 
 [
  {"head": "231", 
   "original": [ "1", "2", "3" ], 
   "values": 
   [
    [ 1, null, 8 ], 
    [ "643", "UTO", "NET" ], 
    [ "Finland", "USA", "Gabon" ]
   ], 
   "status": [ "Modify", "Insert", "Delete" ]
  }
 ]
}

5.1.1.5. Example of "dsParams" request

{ 
 "UserName": "Admin","Password": "",
 "procName":"CntrSpecs",
 "dsParams":
 { "contractorRid":["2"] }
}

5.1.2. Get response with "table data" array.

5.2. Element "table data" contains the following elements:

5.2.1. head (String) - table identifier;

5.2.2. original (array) - array of original names (string);

5.2.3. fields (array) - alternative field names (string);

5.2.4. values (array) - list of field values (array);

5.2.5. status (array) - records statuses (string) , optional.

5.3. Types "tShortDate" and "tLongDate" should be specified in format  "yyyy-mm-dd".

5.3.1. Response fields values of those types will have the same format.