jsonAction request

List of properties in JSON Action request messages

The following properties are part of each jsonAction request message. All are optional except for "action", and "params". APIs often take advantage of the optional properties to implement advanced features.

Example

{
  "requestId": "1",
  "api": "someApi",
  "apiVersion": "1.0",
  "action": "someAction",
  "params": {},

  "responseOptions":
  {
    "binaryFormat":   "hex",
    "dataFormat":     "objects",
    "numberFormat":   "string",
    "includeFields":  [],
    "excludeFields":  [],
    "includePaths":   [],
    "excludePaths":   []
  },
  "debug": "max",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Properties summary

Table 1. Request message properties summary

Property

Description

Default

Type

Limits (inclusive)

action

contains the name of a remote procedure call that the server can execute.

Required - No default value

string

api

(optional) contains the name of an API.

""

string

"admin"

"db"

"hub"

"mq"

"transform"

apiVersion

(optional) specifies the major, minor, and patch versions of the API.

Latest version of the API

string

0 to 12 bytes

authToken

signifies that the client is authenticated and authorized.

Required - No default value

Note

Optional for "pingSession" and "createSession" and defaults to "".

string

0 to 225 bytes

debug

(optional) contains the settings for returning any extra debug information.

"none"

string

"none"

"max"

params

(optional) contains the parameters to an action.

{}

object

requestId

(optional) contains any JSON value to identify a message as assigned by the client.

null

string

number

object

array

Boolean

null

responseOptions

(optional) configures the server to return a customized response.

{}

object

responseOptions

.binaryFormat

(optional) specifies how binary values are returned.

"hex"

string

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

responseOptions

.dataFormat

(optional) specifies what format the results will be returned in.

"arrays"

string

"default"

"arrays"

"objects"

responseOptions

.excludeFields

(optional) specifies which fields are excluded in the response message.

[]

Note

Defaults to the "includeFields" specification.

array

responseOptions

.includeFields

(optional) specifies which fields are returned in the response message.

[]

Note

Defaults to include all fields.

array

responseOptions

.numberFormat

(optional) specifies how numbers are formatted in the JSON response message.

"number"

string

"number"

"string"

A JSON Action request message facilitates remote procedure calls to a server, with the "action" and "params" properties being mandatory. While other properties are optional, they enable advanced features, such as "responseOptions" for customizing the server's response format (e.g., "binaryFormat", "dataFormat", "numberFormat", and field inclusion/exclusion), "api" to specify the target API, "apiVersion" for versioning, "authToken" for authentication (required for most requests except session creation), "debug" for returning troubleshooting information, and "requestId" to uniquely identify messages. Notably, "binaryFormat" is unique as it influences both request and response formatting for binary data, supporting "base64", "hex", or "byteArray" representations, each with trade-offs in readability and payload size.

JSON Action API

JSON Action message format

JSON Action properties

JSON Action parameters

API request structure

Remote Procedure Call (RPC) JSON

request message properties

JSON Action request

JSON DB API

action property JSON

responseOptions JSON request

JSON API development

Backend API integration JSON

Data serialization JSON

handling binary data in JSON

customizing JSON responses

API debugging JSON

JSON request payload

How to build JSON Action request

`"action"`

The "action" property is a required, case-insensitive string enum. It is the name of a remote procedure call that the server can execute.

Possible values depend on the API being used; for a complete list of "actions" see: JSON action REST APIs

`"api"`

The "api" property is an optional, case-insensitive string enum that contains the name of an API. An API can execute one or more actions. It defaults to whatever API is being used.

Possible values:

"db"
Note
For JSON DB API "api" is always "db".
"mq"
"hub"
"admin"

`"apiVersion"`

The server returns the entire version number in the "apiVersion" property for troubleshooting purposes.

"apiVersion" specifies the major, minor, and patch versions of an API.
Examples include "3", "3.1" , and "3.1.23" .
The number to the left of the decimal point is the major API version.
The middle number is the minor API version, which is required only when a patch number is included.
The rightmost number is an optional patch number.

`"authToken"`

The "authToken" property signifies that the client is authenticated and authorized by the server. It is required except in "pingSession" and "createSession". For "pingSession" and "createSession" it defaults to an empty string.

The server generates a unique authentication token in response to "createSession". Clients must include it in all subsequent requests. If the client does not supply a valid "authToken", the server returns error 12031.

You can create a permanent "authToken" by setting the "permanentSession" property to true when you create a session. A permanent "authToken" works like an API key and does not expire.

`"debug"`

The "debug" property is an optional, case-insensitive string enum that causes the server to return debug information. The default value is "none" which is equivalent to omitting this property or similar to setting it to null.

Possible values:
- "none"
- "max"
Setting the "debug" value to anything other than "none" causes the server to pretty-print the JSON that it generates in the response, making it easier to troubleshoot.
Setting to "max" causes the server to return a response that includes the maximum amount of debug information in the response, making it useful for troubleshooting live production data with minimal impact on server resources.
Setting to "none" causes no debug information to be returned, which is useful for production environments that are running well.

`"params"`

The "params" property is an object that contains an action's request parameters as defined by a set of properties. Each action defines its own required and optional properties. See System limits for a comprehensive overview of property requirements and limitations.

`"requestId"`

The optional "requestId" property is typically a string or integer, but can contain any JSON value that is an identifier assigned by the client. The default value is null.

"requestId" can contain any JSON value, including:
- object
- array
- string
- integer
- Boolean
- null
From the client's perspective, "requestId" uniquely identifies a message. The server returns this identifier to the client in its response message, allowing a client to match a request to a response.
It is particularly useful when a client runs JSON DB API over an asynchronous protocol, such as MQTT or WebSocket.
It can be omitted or set to a zero-length string when the client does not need it.

`"responseOptions"`

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

Essential information:

None of these properties are required, but some are mutually exclusive:
- "includeFields" and "excludeFields" are mutually exclusive.
  Use "includeFields" or "excludeFields" to control which record fields are present in the data.
Use "dataFormat" to control whether data comes back as an array of arrays or an array of objects.
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.

"responseOptions":
{
  "binaryFormat": "base64",
  "dataFormat": "arrays",
  "numberFormat": "number",
  "includeFields": [ "name", "email" ],
  "excludeFields": []
}

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

`"dataFormat"`

The "dataFormat" property is an optional, case-insensitive string enum. It defines the format of data being sent to the server. "autoDetect" is the default value.

Note

There are two different but similar versions of the "dataFormat" property. One version occurs in a request, and the other occurs in a response.

Possible values:

"arrays" specifies that the "sourceData" is an array of arrays, which is most efficient.
"objects" specifies that the "sourceData" is an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"autoDetect" instructs the server to automatically detect the format of the data in the "sourceData" property. This is the default.
Omitted or set to null defaults to "autoDetect",

`"excludeFields"`

The "excludeFields" property is an optional array that specifies the fields to exclude from the response message.

Note

When the array is empty or the property is not specified, the "includeFields" specification applies.

Example request

{
  "action": "someAction",
  "responseOptions":
  {
    "excludeFields": ["field1", "field2"]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

`"includeFields"`

The "includeFields" property is an optional array that specifies the fields to include in the response message.

Note

When the array is empty or the property is not specified, all fields are returned.

Example request

{
  "action": "someAction",
  "responseOptions":
  {
    "includeFields": ["field1", "field2"]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}