jsonAction protocol

Standard message pattern for the JSON DB API

Abstract

FairCom JSON DB APIhas a standard request-response message pattern.

The JSON DB API uses a request-response pattern that works over any communications protocol. FairCom has implemented the JSON DB API to work over HTTP.

The typical message pattern is as follows:

The client logs into the server and creates a session using the JSON Admin API "createSession" action. The server sends back an Authorization Token called "authToken" that unique identifies the session. The client includes this information in all subsequent messages to the server so the server can authorize client requests.
The client sends request messages to the FairCom server.
The server returns response messages to the client.

Essential information:

All messages are encoded as JSON.
The structure of each message follows the design specified by jsonAction specification.
Note
The jsonAction specification allows additional properties to be added by an API. FairCom has added additional properties where they are needed. For example, "responseOptions" supports new "includeFields" and "excludeFields" properties that include and exclude database fields from query results.
To support asynchronous communication, such as WebSocket and MQTT:
- The client adds a unique "requestId" property to each request message to allow the client to match a request to a response. The client can assign any JSON value to "requestId" and the server includes the "requestId" and its value in the response message.
- A client can create multiple sessions with the server to process multiple requests in parallel. A client application can use the combination of "authToken" and "requestId" to uniquely identify each message.
FairCom's JSON APIs are stateful because a stateful connection is necessary for data processing tasks, such as retrieving the next set of data from a query or running another step in an ACID transaction.

`"responseOptions"`

The "responseOptions" property is an optional object that configures the server to return a customized response.

Essential information:

An API may add additional properties to "responseOptions".
jsonAction APIs should implement the "binaryFormat" and "numberFormat" properties because JSON does not support binary data and JSON parsers often do not adequately handle large numbers.
Use "binaryFormat" to control how binary data is embedded in JSON strings.
Use "numberFormat" to control whether JSON numbers are rendered as digits or digits embedded in a string.
Use "omit" to remove a property from a response, such as omitting "errorMessage".

"responseOptions": 
{ 
  "numberFormat": "number",
  "binaryFormat": "base64",
  "omit": ["error", "fieldDefs" ]
}

Table 5. "responseOptions" properties summary

Property

Description

Default

Type

Limits (inclusive)

"binaryFormat"

specifies how binary values are returned

"base64"

string

"base64"

"hex"

numberFormat

specifies how numbers are formatted in the JSON response message

"number"

string

"number"

"string"

omit

specifies which properties are excluded in the response message

{}

object

`"binaryFormat"`

The "binaryFormat" is an optional property that controls how binary values are formatted in the JSON request and JSON response message.

Note

Unlike most other response options, the "binaryFormat" property applies to both the request and response. This is special because response options typically apply only to the server’s response.

Essential information

When "binaryFormat" occurs in "params", it specifies how the sender encodes binary values.
For example, when "binaryFormat" is set to "hex", the server expects the binary values in JSON strings to be encoded in hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions", it specifies how the server response should encode binary values embedded in JSON strings.
For example, when "binaryFormat" is set to "hex", the server embeds binary values in strings and encodes them in hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how the server has encoded binary values embedded in JSON strings.
For example, when "binaryFormat" is set to "base64", the server response has encoded binary values in base64 format.
Common values include:
- "binaryFormat": "base64"
  When the server reads and writes from a binary field, it decodes and encodes the binary value as a base64 string.
  - base64 is the most space and processor-efficient encoding scheme for embedding binary data in JSON strings.
  - It is harder for people to interpret.
  - "base64" strings contain the following characters:
    0-9
    A-Z
    a-z
    +
    /
    =
- "binaryFormat": "hex"
  When the server reads and writes from a binary field, it decodes and encodes the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the following characters:
    0-9
    A-F

`"numberFormat"`

The "numberFormat" property is an optional, case-insensitive string enum. It defines the format of JSON numbers returned in a response. "number" is the default value.

Tip

Returning numbers embedded in strings puts your application in charge of how numbers are processed. It ensures JSON parsers and programming languages will not convert numbers to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors.

Possible values:

"number"
- This setting is most efficient because it causes the server to return numeric values as JSON numbers, such as -1.23 .
- JSON numbers are base-ten numbers that may have any number of digits. Large numbers, such as 18446744073709551616.000144722494 are known to cause problems with JSON parsers and some programming languages, such as JavaScript. This is because they use IEEE floating point numbers, which have binary rounding errors and a limited range.
"string"
- This returns the server to embed numeric values in JSON strings, such as "18446744073709551616.000144722494" .
- This is slightly less efficient because it includes two extra double quote characters.
When omitted or set to null, numberFormat defaults to "number".

`"omit"`

The "omit" property is an optional array or strings that contain the name of a JSON property (not a JSON path) that the server should omit from the JSON response. It allows a client to remove jsonAction properties from a response that it does not want.

Things to know:

"omit" reduces the amount of data transferred from server to client and minimizes parsing overhead.
Top-level jsonAction properties can be removed by simply including the property name in the array, such as "errorMessage".
jsonAction properties inside "debugInfo" can be removed by referencing their JSON path, such as "debugInfo.request" and "debugInfo.warnings".
Properties inside "result" can be removed by referencing their JSON path — for example, if an API returns an "extraData" property in "result", it can be removed by specifying "omit": [ "result.extraData" ].
A server requires processing to remove properties from a response; thus, the processing cost of removing properties should be weighed against the network cost of transmitting properties.