`"responseOptions"`

Configures the server to return a customized response

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 1. "responseOptions" property summaries

Property

Description

Default

Type

Limits (inclusive)

binaryFormat

specifies how binary values are returned

"base64"

string

One of the following: "base64", "hex", or "byteArray".

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

variantFormat

(optional) specifies how the server will represent the values of variant fields in its response to your request.

"json"

string

"json"

"binary"

"string"

"variantObject"

`"binaryFormat"`

The "binaryFormat" property designates the formatof binary values embedded in JSON strings. The default value for "binaryFormat" is the "defaultBinaryFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultBinaryFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "hex". Prior to version 13.0.4, the server defaulted it to "base64".

Note

Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

The "binaryFormat" property may occur inside "params", "responseOptions", "defaultResponseOptions" , "result", and "mapOfPropertiesToFields".
- It occurs in "params" when actions create or change values.
- It occurs in "responseOptions" when actions return values.
When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
When "binaryFormat" occurs in "result", it signifies how binary values are represented.
For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields" transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
The following are the possible values for each format.
- "base64"
  When the server reads and writes from a binary field, it represents the binary value as a base64 string.
  - Base64 is harder for people to read and convert to binary.
  - Base64 creates the smallest payload for the most efficient data transmission in JSON.
  - "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
- "hex"
  When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
  - Hexadecimal is easier for people to read and convert to binary.
  - Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
  - Hexadecimal strings contain the characters 0 - 9 and A - F.
- "byteArray"
  When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
  - An array of bytes is easiest for a program to manipulate.
  - An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
  - An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Note

Our examples insert only 3 bytes into "bin". Because the "bin" field has a fixed length of 5 bytes, the server pads unused bytes with 0x00 and stores the result. When a record is retrieved, the server returns all 5 bytes.

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"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.

The "responseOptions" property is an optional object within a JSON Action request that enables clients to customize the format and content of the server's response. It includes "binaryFormat" (defaulting to "base64" but also supporting "hex" or "byteArray") to specify how binary data is encoded in JSON strings, addressing JSON's lack of native binary support. The "numberFormat" property (defaulting to "number" but also offering "string") controls how numbers are represented, helping to prevent precision loss in various programming languages. Additionally, the "omit" property allows for the exclusion of specific properties from the response, reducing payload size and parsing overhead by simply listing the property names or their JSON paths.

JSON Action responseOptions

JSON Action response options

json action response options

API response customization JSON

JSON response format options

binaryFormat JSON API

numberFormat JSON API

omit JSON response property

json response data control

control JSON output format

customize JSON output format

how to customize JSON response

JSON binary encoding options

JSON number representation

how to remove fields from JSON response

JSON number format

JSON binary format

`"variantFormat"`

The "variantFormat" property tells the server how to format the values of variant fields in its response to your request.

The "variantFormat" property has one of the following values: "binary", "json", "string", and "variantObject". It tells the server how to store and return values stored in variant fields. The default value is "json".

Things to know

The server applies the "variantFormat" property to all variant fields affected by a JSON action.
If you want to control the variant format of each field, set the "variantFormat" property to "variantObject" and use variant objects to set the variant type and encoding of each variant field.

The following sections describe each value of the "variantFormat" property.

`"variantFormat": "binary"`

Use the "variantFormat": "binary" setting to encode a variant field's value as a JSON string.
The "binaryFormat" property specifies how to encode the binary value.
- The "binaryFormat": "hex" setting uses hexadecimal to encode a binary value in a JSON string.
- The "binaryFormat": "base64" setting uses Base64 to encode a binary value in a JSON string.
- The "binaryFormat": "byteArray" setting uses an array of integer numbers to encode each byte in the binary value.
When "variantFormat" is "binary", the server sets the variant's type to "binary" and stores raw bytes in the variant field.
The "binary" variant type ensures maximum compatibility and performance across all FairCom APIs, including JSON DB, SQL, CTDB, and ISAM.
The server does not validate the binary value, which can be any sequence of bytes.

`"variantFormat": "json"`

Use the "variantFormat": "json" setting to encode a variant field's value as a JSON value.
- A JSON value can be an object, array, string, number, true, false, or null.
- A binary field value is returned in a JSON string.
- The "binaryFormat" property specifies the format of a binary variant value embedded in a JSON string.
- The "numberFormat" property causes the server to return numbers as JSON numbers or JSON strings.
When "variantFormat" is "json", the server sets the variant's type to "json" and stores a JSON value in the variant field.
- The server validates JSON before it assigns it to a variant field.
- The server converts a variant field to valid JSON before it returns the value of a variant field.
When "variantFormat" is set to "json" in "responseOptions" and the "type" of variant object is "binary", the JSON API returns the binary variant value embedded in a string or as a byte array depending on the "binaryFormat" property in "responseOptions". In other words, when "variantFormat" is set to "json" in "responseOptions", the API returns a JSON value. All variant values can be returned as native JSON values except for binary values because JSON cannot represent them. Thus, when a variant has a binary value and the response option is JSON, the API embeds the binary value in a JSON string according to the value of "binaryFormat".
The server converts variant values to and from JSON as follows:
- JSON null: The server does not store a JSON null; instead it marks the variant field as NULL. If the field is not nullable, the API returns an error.
- JSON string: The server stores a JSON string in the variant field as is. It includes the double quotes before and after the string's value and stores escaped characters without decoding them. For example, the server stores the JSON string, "my // string", as "my // string". The server returns a JSON string exactly as it stores it.
- JSON number: The server stores a JSON number in the variant field as is. A number consists of the following ASCII characters 1234567890+-.eE. For example, the server stores the JSON number -123.45 as the ASCII characters -123.45. The server returns a JSON string exactly as it stores it.
- JSON true & false: The server stores a JSON true and false in the variant field as is. It stores and returns the ASCII characters true or false.
- JSON object & array: The server stores a JSON object and array as is. When it validates the JSON, it minimizes whitespace while preserving the UTF-8 characters representing the actual object or array. For example, the server stores the array [1,2,3] as the UTF-8 characters [1,2,3].

`"variantFormat": "variantObject"`

Use the "variantFormat": "variantObject" setting to encode a variant field's value as a variant object.
When the "insertRecords" and "updateRecords" actions have "variantFormat": "variantObject" in "params", you must assign a variant object to each variant field.
A JSON action returns a variant object for a variant field value when you put "variantFormat": "variantObject" in "responseOptions".

`"variantFormat": "string"`

Use the "variantFormat": "string" setting to encode a variant field's value as a JSON string.
This setting in the "responseOptions" property causes all "getRecords..." actions to return string values from variant fields.
- Binary values are returned as a JSON string containing an embedded binary value. The "binaryFormat" property specifies how to encode the binary value.
- Number values are returned as a JSON number embedded in a string, such as "123.45". The server ignores the "numberFormat" property in the "responseOptions" object.
- Boolean values are returned as a "true" or "false" string.
- String values are returned as a JSON string, which may contain JSON escaped characters.
- JSON values are returned embedded in a string.
  - A JSON object is escaped, encoded, and embedded in a string, such as "{\"key\": \"value\"}".
  - A JSON array is escaped, encoded, and embedded in a string, such as "[1, \"my string\", true ]".
  - A JSON string is returned as a JSON string.
  - A JSON number is embedded in a JSON string, such as "-123.456".
  - A JSON true is returned as "true".
  - A JSON false is returned as "false".
  - A JSON null is returned as "null".
This setting in the "params" property for "insertRecords" and "updateRecords" actions requires a string value to be assigned to each variant field.
- FairCom does not recommend this setting because it can only store strings in variant fields. Consider using the other "variantFormat" options to store many more types of data, such as binary, JSON objects, JSON arrays, numbers, etc.