API Overview

The SCE JSON offers different functionality in distinct modules, and each module is documented separately in the reference manual. Each module has a different format for its input request and output response, which is detailed in the chapter dedicated to that module. However, the general (or top-level) format of the data sent to the SCE JSON needs to be consistent for correct parsing, and is called the "request envelope".

The Request Envelope Object

The request envelope is simply a JSON object which identifies the requested Module, along with a Data object that contains the module specific data fields. The request Data object for each module is thoroughly documented in the chapter dedicated to that module.

Example - Request Envelope for Version Module:

{
  "Module" : "Version",
  "Data" : {}
}

Example - Request Envelope for Loan Module:

{
  "Module" : "Loan",
  "Data" : {...}
}

Request Envelope Object Field Definitions

🟥 Module

The value of the Module field determines which module within the SCE JSON is being requested.

🟥 Data

The Data field contains the module specific request data, and differs depending upon the desired Module. Please reference the chapter dedicated to the module for the required format of the Data object.

Calling the SCE JSON API

Once the request envelope has been created by your application, you will need to send it to the SCE JSON using the appropriate method. Typically, this is done via an HTTP POST request with the body of the request consisting of the request envelope described above. You may also be required to include a specific HTTP header specifyng your API key. These details will be provided by J. L. Sherman and Associates, Inc. and will depend upon how you are accessing the SCE JSON.

Once the request envelope has been successfully sent to the SCE JSON, the SCE JSON will attempt to process the request and will then return a response envelope with the results of the request.

The Response Envelope Object

The response envelope is simply a JSON object which identifies the numeric Result of the call to the SCE JSON, a response Module, along with a Data object that contains the response module specific data fields. The response Data object for each module is thoroughly documented in the chapter dedicated to that module.

Example - Response Envelope for Version Module:

{
  "Result" : 200,
  "Module" : "Version",
  "Data" : {
    "Errors" : [
    ],
    "Warnings" : [
    ],
    "Product" : "SCEJSON",
    "Version" : "2021.07.0",
    "Rootpath" : "/var/task",
    "Copyright" : "(c) 2021 J. L. Sherman and Associates, Inc."
  }
}

Response Envelope Object Field Definitions

🟥 Result

The Result field indicates the status of the API request. Please see the following table for what the API Result code mean. A successful call will result in a Result field value of 200 (API_OK). Any other value indicates that an error was encountered.

🟥 Module

The value of the Module field determines which module within the SCE JSON generated the response. If the value of the Result field is 200 (API_OK), then the value of Module will be the same as the value of the Module field in the request envelope. If the value Result field is something other than 200 (API_OK), then the SCE JSON has encountered an API ERROR condition, and the value of the this field will be set to "Error" to indicate that the Data field should be parsed as an API Error response.

🟥 Data

The Data field contains the module specific response data, and differs depending upon the returned Module. Please reference the chapter dedicated to the module for the required format of the Data object.

API Error Response

As mentioned above, if the SCE JSON was not able to successfully dispatch a request due to one of several possible error conditions, an API Error Response will be returned. Here are a few examples of SCE JSON requests that generate API Error Responses

Example - Request with invalid JSON and resulting response:

{
  "Module" : "FooBar"
  "Data" : {}
}

{
  "Result" : 400,
  "Module" : "Error",
  "Data" : {
    "Errors" : [
      "Exception while parsing JSON input. \"EJSONParser: Error at line 3, Pos 8:Expected , or ], got token \"Data\".\empty
    ]
  }
}

Example - Request with no Module field and resulting response:

{
  "Data" : {}
}

{
  "Result" : 400,
  "Module" : "Error",
  "Data" : {
    "Errors" : [
      "Bad API request. No 'Module' string field present."
    ]
  }
}

Example - Request with no Data field and resulting response:

{
  "Module" : "Version"
}

{
  "Result" : 400,
  "Module" : "Error",
  "Data" : {
    "Errors" : [
      "Bad API request. No 'Data' object field present."
    ]
  }
}

Example - Request with invalid Module and resulting response:

{
  "Module" : "FooBar",
  "Data" : {}
}

{
  "Result" : 403,
  "Module" : "Error",
  "Data" : {
    "Errors" : [
      "API not found. No Module named 'FooBar' found."
    ]
  }
}

API Error Response Data Object Field Definition

The Data object for an API Error Response contains a single field which returns a description of the API Error.

🟥 Errors

The Errors[] field contains an array of Strings which describe the error conditions which were encountered. For an API Error Response, the length of the Errors[] Array should always be one (1).