jsonAction request message

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

{
  "authToken": "serverSuppliedAuthTokenMayBeOptional",
  "requestId": "1",

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

  "responseOptions":
  {
    "binaryFormat":   "hex",
    "numberFormat":   "string"
  },

  "debug": "max"
}

Property summary

Table 1. Request message properties 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 action

""

string

"apiVersion"

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

Latest version of the API

string

Minimum length: 0 bytes

Maximum length: 20 bytes

"authToken"

signifies that the client is authenticated and authorized

null

string

number

object

array

Boolean

Minimum length: 0 bytes

Maximum length: 255 bytes

"debug"

contains the settings for returning any extra debug information

"none"

string

"none"

"max"

"maxOnError"

"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 an action that the server can execute.

Things to know:

Each solution that implements an API using jsonAction defines names for the actions it supports.
The "api" and "action" properties work together to define a unique name for an action (see "api").
An API is a namespace for an "action" — for example, a server may support multiple jsonAction APIs. An action within one of these APIs may have the same name as an action in another API.

`"api"`

The "api" property is an optional, case-insensitive string enum that contains the name of an API. It defaults to an empty string.

Things to know:

The "api" and "action" properties work together to define a unique identifier for an action (see "action").
An API is a namespace for an "action" — for example, a server may support multiple jsonAction APIs. An action within one of these APIs may have the same name as an action in another API.

`"apiVersion"`

In a request, the "apiVersion" property is optional. When omitted, the server uses the latest version of an API. When present, the server uses the specified version of the API.

In a response, the server returns the "apiVersion" property in the optional "debugInfo" property to indicate the full version of the API that processed the action.

Things to know:

"apiVersion" specifies the major, minor, and patch versions of an API.
- Each part of an API version is an integer number separated by the period character — for example "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.
A server may support multiple APIs and each API is versioned independently (see "api").
"apiVersion" follows the semantic versioning scheme.
- Major versions of an API are incremented when incompatible changes have occurred, such as adding a new required property, changing the type or name of a property, or changing a behavior.
- Minor versions of an API are incremented when optional properties and values are added to an API.
- Patch versions of an API are incremented to track release changes.
- Minor and patch versions of an API can change without breaking applications.
- Sometimes a minor or patch change to an API unintentionally breaks compatibility. When this occurs, an application can specify a previous "apiVersion".
- A server should simultaneously support multiple versions of its APIs to ensure application compatibility.
A jsonAction request should omit the "apiVersion" property when it wants the server to use the latest version of an API.
A jsonAction request should include the "apiVersion" property when it wants the server to use a specific version of an API. This is useful when the latest version of an API has a bug or new behavior that is incompatible with the requesting application.
- The "apiVersion" property in a request may include a partial version number, such as "1" to specify the latest major version or "1.1" to specify the latest minor version.
- The server returns an error when the specified API is not supported.
A jsonAction response always includes the "apiVersion" property in the optional "debugInfo" property.
- When the "debugInfo" property is included in the response, the "apiVersion" property is always included inside it.
- In a jsonAction response, the value of the "apiVersion" property is always set to the full version number of the API, such as "3.0.1".

`"authToken"`

The "authToken" property is typically a string but may be any type of JSON value. It signifies a client is authenticated and authorized to perform some actions.

Things to know:

"authToken" is supplied by the server in response to an API action, such as "login", "connect", or "createSession".
A client receives an "authToken" from the server when it logs into a server.
An API may or may not require "authToken" to validate that the client is authenticated and authorized.
"authToken" may be required for some actions and optional for others.
An API returns an unauthorized error when it rejects an "authToken".
"authToken" is intentionally designed to support any JSON type to accommodate any type of authentication and authorization scheme supported by a server.

`"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 setting it to null.

Things to know:

Possible values:
- "none"
- "min"
- "max"
- "minOnError"
- "maxOnError"
Setting to "none" or null causes no debug information to be returned. This is useful for production environments that are running well.
Setting the "debug" value to anything other than "none" and null causes the server to pretty-print the JSON that it returns making it easier to troubleshoot.
Setting to "min" in the causes the server to return a minimal amount of extra debug information in the response. A server may ignore this value if it does not have a minimum debug level.
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. A server should support this value.
Setting "debug" to "max" causes the server to return a response that includes the maximum amount of debugging information, which includes the entire request body and query execution plans, making it useful when you need to troubleshoot a specific message.
Maximal debugging information consumes more computational power and resources. It is typically used during development and QA.
Setting "debug" to "minOnError" causes the server to return minimal debug information when an error occurs. This is temporarily turned on in production environments to troubleshoot issues. A server may ignore this value if it does not have a minimum debug level.
Setting "debug" to "maxOnError" causes the server to return maximal debug information when an error occurs. This is temporarily turned on in production environments that need to deeply troubleshoot issues. It is typically turned on in continuous test environments. A server should support this value.
A server may define additional values and behaviors for "debug".

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

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

Property

Description

Default

Type

Limits (inclusive)

"binaryFormat""binaryFormat"

determines how binary values are returned

"base64"

string

"base64"

"hex"

"numberFormat"

controls how numbers are formatted in the JSON response message

"number"

string

"number"

"string"

"omit""omit"

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

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

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

In this section:

API

jsonAction.org