jsonAction request

List of properties in JSON Action request messages

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",
  "api": "someApi",
  "apiVersion": "1.0",
  "action": "someAction",
  "params": {},

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

 

Property summaries

Property Description Default Type Limits (inclusive)

action

 The "action" property contains the name of a remote procedure call that the server can execute.

Required - No default value

 string  

api

 The "api" property contains the name of an API. Optional with default of "" string

"admin"

"db"

"hub"

"mq"

"transform"

apiVersion

The "apiVersion" property specifies the major, minor, and patch versions of the API.

 Latest version of the API string 0 to 12 bytes

authToken

The "authToken" property 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

 The "debug" property contains the settings for returning any extra debug information. Optional with default of "none" string

"none"

"max"

params

The "params" property contains the parameters to an action.

Optional with default of {}

 object 0 or more parameters

requestId

 The "requestId" property contains any JSON value to identify a message as assigned by the client. Optional with default of null string enum

string

number

object

array

Boolean

null

responseOptions

The "responseOptions" property configures the server to return a customized response.

  • 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.
    • "includePaths" and "excludePaths" are mutually exclusive.
      • Use "includePaths" or "excludePaths" to control which JSON properties are included in the data.
  • A JSON path includes the JSON field name plus the path of the property within the JSON field.
  • Use "omit" to remove a property from a response, such as omitting "errorMessage".
  • Use "dataFormat" to control whether data comes back as an array of arrays or an array of objects.
  • Use "numberFormat" to control whether JSON numbers are rendered as digits or digits embedded in a string.
  • Use “stringFormat” to change how “char”, “varchar”, “lvarchar”, and “variant” string field values are returned. 
  • Use "variantFormat" to control how the server formats the values of variant fields in its response.
Full example
    "responseOptions": 
    { 
     "omit": ["error", "fieldDefs" ]
     "dataFormat": "arrays", 
     "numberFormat": "number",
     "includeFields": [ "name", "email" ],
     "excludeFields": [],
     "includePaths": [],
     "excludePaths": [ "email.domain" ],
     "binaryFormat": "base64",
     "stringFormat": "json",
     "variantFormat": "json"
    }
 Optional with default of null object

"omit"

"dataFormat"

"numberFormat"

"includeFields"

"excludeFields"

“includeBookmarks”

"includePaths"

"excludePaths"

"binaryFormat"

"stringFormat"

"variantFormat"

 

responseOptions

.binaryFormat

 The "binaryFormat" property designates the format of binary values embedded in JSON strings. For more details, see "binaryFormat".  Optional with default of "hex" string One of the following: "base64", "hex", or "byteArray".

responseOptions

.dataFormat

The "dateFormat" property specifies the format of a date or a datetime embedded in a JSON string. It applies to user-provided JSON and to server-generated JSON. The server uses it when it needs to transform or convert a date or datetime embedded in a JSON string into a FairCom date or timestamp. It also uses it when it needs to convert a date or datetime field value into a date embedded in a JSON string.

The default value for "dateFormat" is the "defaultDateFormat" property defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultDateFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "iso8601" because the ISO8601 date is the defacto standard in JSON.

The enumerated string defines how the server parses a date in a JSON string and how it writes a date into a JSON string. The following key explains the parts of each enumerated value:

  • ccyy is a four-digit year (0000-9999).
  • yy is a two-digit year (00-99).
  • mm is a two-digit month (01-12).
  • dd is a two-digit day of the month (01-31).
  • hh is a two-digit hour (00-23).
  • . represents one character that can be one of the following values: /, ., or -.
  • "utc", "iso8601", and "ccyy.mm.dd" are the same.
UTC datetime format

Coordinated Universal Time (UTC) is an industry-standard for dates and times that uses the ISO8601 datetime format: "ccyy-mm-ddThh:mi:ss.fffz" or "ccyy-mm-ddThh:mi:ss.fff±hh:mi":

  • Variable parts
    • ccyy is a four-digit year.
    • mm is a two-digit month (01-12).
    • dd is a two-digit day of the month (01-31).
    • hh is a two-digit hour (00-23).
    • T is the letter T or the space character. It is required only when the time is present.
    • mi is a two-digit minute (00-59).
    • ss is a two-digit second (00-59).
    • fff is an optional fraction of a second with up to three digits of precision.
    • ± is an optional + or - character representing a positive or negative timezone offset. It is required only when a timezone offset is present.
  • Constant parts
    • - separates the year, month, and day.
    • : separates the hour, minute, and second.
    • . separates the second from a fraction of a second. It is required when the fraction is present.
    • Z is optional and represents the UTC timezone (also called Zulu time), which represents the timezone offset of +00:00.
  • Examples
    • 2025-07-11T16:18:33Z
    • 2025-07-11T16:18:33+00:00
    • 2025-07-11 16:18:33.9-07:00
 Optional with default of "iso8601" string enum

"ccyy.mm.dd"

"mm.dd.ccyy"

"mm.dd.yy"

"dd.mm.ccyy"

"dd.mm.yy"

"ccyymmdd"

"yymmdd"

"iso8601"

"utc"

responseOptions

.excludeFields

 The "excludeFields" property specifies which fields are excluded in the response message.

Optional with default of []

Note Defaults to the "includeFields" specification.

 

 array  

responseOptions

.includeFields

 The "includeFields" property specifies which fields are returned in the response message.

Optional with default of []

Note Defaults to include all fields.

 

 array  

responseOptions

.numberFormat

The "numberFormat" property defines the format of JSON numbers. For more details, see "numberFormat". 

 Optional with default of "number" string

"number"

"string"

 

actionrequest jsonrequest

Was this article helpful?

Give feedback about this article

Related Articles