The Sherman Calculation Engine API Server.
10K+
The SCE API Server provides a HTTP REST interface for the Sherman Calculation Engine. It is packaged to make it easily deployed using Docker running on the Linux/amd64 and Linux/arm64 platforms. Using this deployment configuration easily allows our partners to spin up one or more instances of the SCE in a local or cloud environment.
Step 1: Run the SCE API Server Docker container
$ docker run -d -p8080:8080 --name sce-api shermanloan/sce-api-server
This will spin up the latest version of the SCE API Server Docker image in its default configuration. Please see the following sections which document how to customize this configuration, as well as how to call the API. Note that you will need an API key to make use of the SCE API Server.
data/ - directory containing sample setup files, which configure various calculation and insurance settings for a given account.
samples/ - directory containing sample SCEX XML requests for the various modules supported in the SCEX.
xml/ - directory containing DTD files for all SCEX requests (input). The Output/ subdirectory holds DTD files for all SCEX responses (output).
Dockerfile - the file which tells docker how to build an image from the files in this distribution.
README.md - this document.
sce-api-server - the SCE API Server.
sce-api-server.cfg - the configuration file for the SCE API Server.
sce-api-server-health-check - a small application which verifies that the sce-api-server is functioning correctly.
As mentioned above, the sce-api-server.cfg file contains settings that alter the functionality of the SCE API Server. The default contents of the file are as follows:
[Settings]
Port=8080
LogLevel=0
LogFile=/var/log/sce-api-server.log
RootPath=
DefaultPath=
ApiKey=
Port - The port number on which the server will listen for HTTP client connections.
LogLevel - This setting determines the amount of information that is logged. A value of zero (0) indicates that minimal information is logged (errors, service start / stop / pause /resume). A value of one (1) adds information on each connection (remote address connection, URL, and Api Key used). Level two (2) logging adds the request from the client. Finally, log level three (3) adds the response sent back to the client. Please note that log levels 1 and up can generate a significant amount of information, so be sure to monitor the free space available on the filesystem where the log file is stored.
LogFile - If the value of this attribute is 'system', then the SCE API
Server will use the system logfile. If you do not want to use the system log
file, then specify the fully qualified filename using this attribute. Note
that in the Docker build of the SCE API Server, the specified log file
(/var/log/sce-api-server.log) is redirected to /dev/stdout in the Dockerfile so
that the logfile can be monitored using docker logs.
RootPath - If specified, this setting will be used as a prefix for setup file
data directory paths. As an example, if you wanted to only allow API calls to
specify subdirectories of the /etc/sce/ directory, then you would set the
value of this attribute to /etc/sce/. Leaving the value empty allows API
calls to specify any directory path. This setting is only relevant if you
require the use of setup files (see the description of the data/ directory
above). Please also see the x-sce-datapath header field in the section below
detailing the API Interface.
DefaultPath - Default data directory for requests (used when client doesn't provide x-sce-datapath)
ApiKey - This setting configures the default ApiKey to be used for each request. If not set, then every request sent to
the server will need to include the x-sce-apikey header, described below.
The SCE API Server exposes a few endpoints for your application to call, each of which will be documented below. All endpoints share a few things in common: request header fields, response codes, and response header fields.
Two request header fields are supported:
x-sce-datapath - allows the request to specify a default data directory. Note that if the RootPath in the sce-api-server.cfg file is not empty, then the value of this header field will be appended to the RootPath.
x-sce-apikey - allows the request to specify an API Key. If a valid Api Key has been configured in the sce-api-server.cfg file, then this header field is not required. If the x-sce-apikey header field is included in the request, then it will be used no matter what is present in the config file.
Once a client has submitted a request to the server, the server will attempt to process it and return the results as an HTTP response. The response code returned will be one of the following values:
200 - Valid Api Key, request sent to SCE, and SCE returned without an error.
401 - Unauthorized access, Api Key invalid.
500 - Server error. Either the SCEX or the SCE API Server encountered an error.
For successful responses, the Content-Type field will be set to the appropriate
type (either application/xml or application/json), a header field named
x-sce-apikey-expires whose value returns the expiration date of the API Key
will be present, and the SCE API Server response will make up the BODY.
Each endpoint supported by the SCE API Server is documented below.
To query the version of the SCEX, simply send a GET request to http://server:port/scex/api/v1/version.
To send a single XML request to the SCEX, simply send a POST request to http://server:port/scex/api/v1/request with the BODY of the POST request holding the XML request to be sent to the SCEX. Documentation for the various XML requests supported by the SCEX is found in the SCEX Reference Manual.
To send a batch request to the SCEX, simply send a POST request to http://server:port/scex/api/v1/batch with the BODY of the POST request holding a JSON object or array with the multiple XML request to be sent to the SCEX.
If the BODY is a JSON object, then all top level JSON string fields of the
object with field names that end in SCEX will be treated as an XML request
and send to the SCEX. The response will contain all fields which were
ignored, along with all fields passed to the SCEX with the values of these
fields holding the SCEX XML response.
JSON object request sample:
{
"Version_SCEX" : "<inVERSION/>",
"Accounts_SCEX" : "<inACCOUNT/>",
"DoNotParse" : "The SCEX will not parse me, since the end of the field name is not 'SCEX'.",
"AlsoWontParse_SCEX" : {
"Reason" : "This is a JSON Object"
}
}
JSON object response sample:
{
"Version_SCEX": "<?xml version=\"1.0\" standalone=\"no\" ?>\r\n<!DOCTYPE outVERSION SYSTEM \"outVERSION.dtd\"...",
"Accounts_SCEX": "<?xml version=\"1.0\" standalone=\"no\" ?>\r\n<!DOCTYPE outACCOUNT SYSTEM \"outACCOUNT.dtd\"...",
"DoNotParse": "The SCEX will not parse me, since the end of the field name is not \"SCEX\".",
"AlsoWontParse_SCEX": {
"Reason": "This is a JSON Object"
}
}
Alternatively, the request BODY can also be sent as a JSON array of strings, each of which will be treated as an XML request to be sent to the SCEX.
JSON array request sample:
["<inVERSION/>", "<inACCOUNT/>"]
JSON array response sample:
[
"<?xml version=\"1.0\" standalone=\"no\" ?>\r\n<!DOCTYPE outVERSION SYSTEM \"outVERSION.dtd\" >\n<outVERSION>\n...",
"<?xml version=\"1.0\" standalone=\"no\" ?>\r\n<!DOCTYPE outACCOUNT SYSTEM \"outACCOUNT.dtd\" >\n<outACCOUNT>\n..."
]
To send a JSON request to the SCE, simply send a POST request to http://server:port/scejson/api/v1/request with the BODY of the POST request holding the JSON request to be sent to the SCE. Documentation for the various JSON requests supported by the SCE API Server is found in the SCEJSON Reference Manual.
LogLevel is >= 1 (default value is 0), each request is logged to the appropriate log file. Previously, valid API keys were logged with each request. With this release, only the first four characters of the API key will be logged with "+..." appended to it. Invalid API keys are still logged in their entirety.application/xml to application/json.NEW - Base Linux image updated from Alpine 3.11 to 3.14.
NEW - The SCEX Http API Server has been renamed the SCE API Server. The names of some files in the Docker image have changed, however it operates identically to previous releases (with the addition of the new functionality noted below).
NEW - The SCEX Http API Server now exposes a batch request URL at /scex/api/v1/batch. To send multiple XML requests using one API call, you can send one of the following as the BODY of your POST request:
(i) a JSON array containing strings which represent each individual XML request to be sent to the SCEX. Any array member that is not a JSON string will be ignored and appended to the result array returned to the calling application.
(ii) a JSON object. All child fields of the JSON object will be examined, and if of type JSON string and if the field name ends with "SCEX", then the field value will be treated as an individual XML request to be sent to the SCEX, with the response XML added as a field of the same name in the JSON object returned to the calling application. All fields of the JSON object which are not JSON strings or do not end with "SCEX" will not be processed by the SCEX and will be added to the JSON object response unchanged.
Content type
Image
Digest
sha256:c42859cba…
Size
7.6 MB
Last updated
14 days ago
docker pull shermanloan/sce-api-server