Description of API for Working with StoreHouse5 Server via HTTP

The SH5WAPI2 server makes it possible to receive and transmit information to the StoreHouse5 server via JSON files (www.json.org) via the HTTP protocol.

The StoreHouse5 server communicates with the outside world exclusively using procedures identified by name. The procedure takes datasets (tables) as parameters and fills them with the requested information in response. SH5 datasets can be single-line and multi-line.

There are two operations available:

• Request a list of procedure datasets: /api/sh5struct
• Perform the procedure: /api/sh5exec.

Using the specified paths, execute a POST request with the transfer of the following JSON file to Content:

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

• UserName (string) — StoreHouse5 username
• Password (string) — StoreHouse5 user password
• procName (string) — StoreHouse5 procedure name.

These three parameters are required in any request to the server. As a result of executing the request, a response JSON file will be sent. A response example:

{
"errorCode": 1,
"errMessage": " XDivisions procedure not found.",
"Version": "0.1.4"
}

• errorCode (number) — the error code
• errMessage (string) — the error text
• Version (string) — SH5WAPI2 server version.

These three values are necessarily present in any server response. If the request is successful, the ErrorCode will be equal to 0, and other elements will be present:

• actionName (String) — the name of the StoreHouse5 procedure
• ActionType (String) — Structure or Execute — the requested operation
• shTable (array) — table structure or table with data list of objects.

ErrorCode values: 0 or 1.

JSON files must be UTF-8 encoded.

Requesting a List of Procedure Datasets

The request is sent via the /api/sh5struct path and contains only three obligatory parameters listed above. The response contains an array of table structure elements.

The table structure object contains the following elements:

• head (String) - table id
• SingleRow (Bool) - single-line dataset (true) or multi-line (false)
• fields (array) - a list of table field objects.

The table field object contains the following elements:

• path (String) — the original name of the field
• type (String) — the field type
• size (String) — the field size
• alt (String) — optional, an alternative field name

Example of a successful 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 }
    ]
   }
  ]
 }

Performing the procedure

The request is sent via the /api/sh5exec path. The data is transmitted to the procedure via the Input parameter. Or, for compatibility with the old version, via the dsParams parameter. The second method is outdated and may be excluded in the future. The Input parameter (array) contains a list of data table objects. The dsParams parameter (object) contains data field objects, while only alternative field names are allowed.

The response contains an array of table with data elements.

The tShortDate and tLongDate types must be transmitted in the yyyy-mm-dd format. If there are such data types in the response, then they will be in this very format.

The data table object contains the following elements:

• head (String) — the table id
• original — an array of original field names (string)
• fields — an array of alternative field names (string)
• values — an array containing arrays of field values
• status — optional, an array of record statuses (string)

Example of a request with the Input parameter:

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

Some procedures for modifying or deleting a record in a table require transmitting its status. In this case, you need to add the status array to the data table object, in which you list the necessary statuses for each record. Possible options: Insert, Modify, Delete. By default, all records get the Insert status.

Example of a request with record statuses:

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

The data field object is an array containing the field values for all records in the table. Example of a request with the dsParams parameter:

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

Configuring the Server

Command line parameters:

• /Install — install as a service
• /Uninstall — uninstall the service
• /Desktop — run as an application, stop via the tray icon
• /Silent — do not show windows when installing or uninstalling the service
• /Name:SH5WAPI2 — a service or server name
• /Port:9797 — TCP port where the server is waiting for requests.

In the command line, the server receives the number of the TCP port, on which it is waiting for clients to connect, and its own name. The default port is 9797 and the name is SH5WAPI2. The name is used to determine the subdirectory where the server takes the rest of its settings and writes log files, and in the case of launching the service, it is also the name of the service. In the specified subdirectory (=name) of the server launch folder, the server reads the CONFIG.INI text configuration file of the following type:

; logging level 0-do not keep a log; 1-keep the main logs;
;2-to save the latest Headers and Content in files
LogLevel = 2

;to connect to the StoreHouse5 server, use: 0-local protocol; 1-TCP;
sh5tcp = 0

;the name of the StoreHouse5 server to connect via the local protocol
sh5server = SDBSERV

;the computer where the StoreHouse5 server is running for connecting via TCP
sh5host = 127.0.0.1

;the port on which the StoreHouse5 server is running for connecting via TCP
sh5port = 7771

;the code page of the StoreHouse5 database
sh5cp = 1251

;SSL certificate file, if a secure connection is required
;SSL_cert = cert1.pem

;SSL private key file, if a secure connection is required
;SSL_priv = priv1.pem

;SSL password to the private key, if it is encrypted
;SSL_psw =

;certificate authority file, optional
;SSL_CA =

The following libraries are used to work with the SH5 server:

• borlndmm.dll
• sdbcli.dll
• domm.dll
• dset.dll
• cc3260.dll

They should be located in the server launch folder. The server writes its log files to the next-level LOGS subdirectory. In the TEMPLATE subdirectory of the server launch folder, there are optional JSON files with alternative names of the fields of the StoreHouse procedure datasets. They are used if someone wants to refer to the fields not by the original name, but by a more understandable one. If there is an alternative name, the ability to work with the original name is preserved — both are valid. A file with alternative field names is created from the response to the request for the procedure dataset structure. You just need to add the alt attribute to the required fields. The file name consists of the procedure name plus _desc.json. To check the operation of the server, you can use the Swat.exe test program.