Skip to main content

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

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

"binaryFormat"

The "binaryFormat" property is optional and controls how binary values are formatted in the JSON request and JSON response messages.

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.

Essential information

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

"variantFormat"

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