Skip to main content

jsonAction request

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",
  "authToken": "anAuthorizationTokenFromTheServer",

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

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

  "debug": "max"
}

Property summary

Table 1. Request message property summaries

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 enum

"api"

contains the name of an API

""

string enum

"db"
"mq"
"hub"
"admin"

"apiVersion"

specifies the major, minor, and patch versions of the API

Latest version of the API

string

Minimum length: 0 bytes
Maximum length: 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

Minimum length: 0 bytes
Maximum length: 255 bytes

"debug"

contains the settings for returning any extra debug information

"none"

string

"none"
"max"

"params"

contains the parameters to an action

{}

object

"responseOptions"

configures the server to return a customized response

{}

object

"requestId"

contains any JSON value to identify a message as assigned by the client

null

string
number
object
array
Boolean
null


"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. It is required by the jsonAction standard.

Possible values depend on the API being used, for a complete list of "actions" see:

"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 "apiVersion" property is returned by the server. It is always the entire version number of the JSON DB API for troubleshooting.

Things to know:

  • "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. It is required except in "pingSession" and "createSession". For "pingSession" and "createSession" it defaults to an empty string.

Things to know:

  • It is supplied by the server in response to the connect action.

  • Clients must include it in all subsequent requests to validate that the client is authenticated and authorized. If the client does not supply the correct values, the server returns an unauthorized error.

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

Things to know:

  • Possible values:

    • "none"

    • "max"

  • Setting the "debug" value to anything other than "none" causes the server to pretty-print the JSON that it returns making it easier to troubleshoot.

  • Setting to "max" causes the server to return a response that includes the maximum amount of extra debug information in the response making it useful for troubleshooting live production data with minimal impact on server resources.

  • Setting to "none" cause 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 parameters. Each action defines its own required and optional properties.

"responseOptions"

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

Things to know:

  • 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.

"binaryFormat"

The "binaryFormat" property controls how binary values are formatted in the JSON request and JSON response message. The default value is "base64".

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.

Things to know:

  • When "binaryFormat" occurs in "params" it specifies how the sender encodes binary values.

    For example, when  "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be embedded in strings and encoded in hexadecimal format.

  • When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" specifies how the FairCom server should encode binary values in the response.

    For example, when "binaryFormat" is set to "hex", the FairCom server embeds binary values in strings and encodes them in hexadecimal format.

  • When "binaryFormat" occurs in "result" signifies how it has encoded binary values that are embedded in strings.

    For example, when "binaryFormat" is set to "base64", the FairCom server has encoded binary values in the response in base64 format.

Possible 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.

    • This is the default

    • "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

"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 another occurs in a response.

Possible values:

  • "arrays"

    This causes the server to return results as an array of arrays, which is most efficient.

  • "objects"

    This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

  • "autoDetect"

    This causes the server to automatically detect the format of the data in the "sourceData" property. This is the default.

  • Omitted or set to null

    This defaults to "autoDetect", which causes the server to automatically detect the format of the data in the "sourceData" property.

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

Possible values:

  • "number"

    This causes the server to return numeric values as JSON numbers, such as -18446744073709551616.000144722494 .

    This is most efficient.

    JSON represents 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, which are limited to the smaller range and binary rounding errors of IEEE floating point numbers.

  • "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

    Returning numbers embedded in strings ensures JSON parsers and programming languages will not automatically convert the number to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors. This allows your application to control how numbers are processed.

  • Omitted or set to null

    This defaults to "number".

"requestId"

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

Things to know:

  • "requestId" can contain any JSON value including:

    • object

    • array

    • string

    • integer

    • Boolean

    • null

  • From the client's perspective, "requestId" uniquely identifies a message where the server returns this identifier to the client in its response message. This allows 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.