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

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

 

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

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

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

The "variantFormat" property has one of the following values: "binary", "json", "string", and "variantObject". It tells the server how to store and return values stored in variant fields. 

The server applies the "variantFormat" property to all variant fields affected by a JSON action, such as all variant fields inserted by the "insertRecord" action or all variant fields returned by the "getRecordsByIndex" action. If you want more control, set the "variantFormat" property to "variantObject" and you can use variant objects to independently set the variant type and encoding of each variant field in a JSON action.

A variant field is a flexible, strongly-typed field. It is flexible because each variant field in each record can store any type of data. It is strongly typed because each variant field in each record stores the type of value it contains.

A variant field's type can currently be set to "binary", "json", "string", and "boolean" values. In the future, you will be able to set it to other values, such as "jpeg", "xml", and user-defined types.

The following sections describe each value of the "variantFormat" property.

 

"variantFormat": "binary"

  • Use the "variantFormat": "binary" setting to store and return variant field values as binary values embedded in JSON strings.
  • The "binary" variant type ensures maximum compatibility and performance across all FairCom APIs, including JSON DB, SQL, CTDB, and ISAM.
  • When "variantFormat" is "binary", the server sets the variant's type to "binary" and stores raw bytes in the variant field.
  • The binary value can be any sequence of bytes.
  • The server does not validate the binary value.
  • The "binaryFormat" property specifies how the client and server format binary value. For example, the "hex" value embeds hexadecimal numbers in a JSON string.
 

"variantFormat": "json"

  • Use the "variantFormat": "json" setting to store and return variant field values as JSON values.
  • The "json" variant type provides maximum convenience in FairCom's JSON APIs.
  • The server validates JSON before it assigns it to a variant field.
  • The server converts a variant field to valid JSON before it returns the value of a variant field.
    • The "binaryFormat" property specifies the format of a binary variant value embedded in a JSON string.
    • The "numberFormat" property causes the server to return numbers as JSON numbers or JSON strings containing embedded numbers. All languages and JSON parsers work well with strings containing embedded numbers – even extremely large and small numbers.
  • When "variantFormat" is "json", the server sets the variant's type to "json" and stores a JSON value in the variant field.
    • The server does not store a JSON null; instead it marks the variant field as NULL. If the field is not nullable, the API returns an error.
    • The server stores a JSON string in the variant field as is. It includes the double quotes before and after the string's value and stores escaped characters without decoding them. For example, the server stores the JSON string, "my // string",  as "my // string". The server returns a JSON string exactly as it stores it.
    • The server stores a JSON number in the variant field as is. A number consists of the following ASCII characters 1234567890+-.eE. For example, the server stores the JSON number -123.45  as the ASCII characters -123.45. The server returns a JSON string exactly as it stores it.
    • The server stores a JSON true and false in the variant field as is. It stores and returns the ASCII characters true or false.
    • The server stores a JSON object and array as is. When it validates the JSON, it minimizes whitespace while preserving the ASCII characters representing the actual object or array. For example, the server stores the array [1,2,3]  as the ASCII characters [1,2,3].
  • Use the "variantFormat": "variantObject" setting to store and return variant field values as a variant object.
  • The variant object defines everything the server and client need to know about a variant, including its type, value, value encoding, and storage encoding.
  • The "variantObject" variant type provides maximum flexibility across all FairCom APIs and programming languages.
  • A variant object is a JSON object containing the following properties: "schema", "value", "valueEncoding", and "type". The "schema" property must have the value "jsonaction.org/schemas/variantObject".
  • When "variantFormat" is "variantObject", the server parses the variant object and uses its properties to determine how to store the variant value.
    • The "value" property contains the variant field's value .
    • The "valueEncoding" property specifies how the value is encoded so the server and client can decode the value. For example, assigning "hex" to "valueEncoding" indicates the "value" property contains a binary value embedded in a string as hexadecimal characters. The server decodes the value before storing it in the variant field. In FairCom's JSON APIs, the "binaryFormat" property in the "responseOptions" object specifies how the server encodes the binary value before returning it.
    • The "type" property specifies the variant's type, such as "json", "binary", and "string". In the future, the FairCom server will support additional types, such as "jpeg", "xml", and user-defined types.
  • When the "insertRecords" and "updateRecords" actions have "variantFormat": "variantObject" in "params", you must assign a variant object to each variant field.
  • A JSON action returns a variant object for a variant field value when you put "variantFormat": "variantObject" in "responseOptions".
 
Variant object examples
Binary value in a variant object

Add "binaryFormat": "base64" to "responseOptions" to tell the server to encode the variant value as Base64.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "ewogICJrZXkiOiAidmFsdWUiCn0=",
  "valueEncoding": ["base64"],
  "type": "binary"
}
Number in a variant object

Add "numberFormat": "string" to "responseOptions" to tell the server to embed the number in a string.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "123.45",
  "valueEncoding": ["string"],
  "type": "number"
}

Add "numberFormat": "number" to "responseOptions" to tell the server to encode the number as a JSON number.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": 123.45,
  "type": "number"
}
Boolean in a variant object
{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": true,
  "type": "boolean"
}
String in a variant object
{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "A JSON string with embedded \" double quote.",
  "type": "string"
}
JSON in a variant object
{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": [1,"2",{"key": "value"}],
  "type": "json"
}

 

"stringFormat"

The "stringFormat" property in "responseOptions" changes how "char", "varchar", "lvarchar", and "variant" string field values are returned.

This property applies to all "getRecords..." actions, except for "getRecordsUsingSql" because SQL controls the format of strings it returns.

 

Options

"json" (default)

  • Returns "char", "varchar", "lvarchar", and "variant" string values as hexadecimal numbers embedded as JSON strings, such as "6d7920737472696e67".
  • Returns the raw binary value stored in the field, encoded as a hexadecimal.
  • Always twice the length of the original string.
  • Useful for returning legacy values that are incompatible with UTF-8 so they can be fixed.
  • When the "stringFormat" property is "hex", the API ignores the setting of "fixedLengthCharFormat" because it returns the field's raw value.  It includes pad characters in the hex dump. For example, "value     " in a char(10) field returns "76616c75652020202020".
  • When "variantFormat" is "string" or "json", a variant field returns binary values embedded in a string, such as "6d7920737472696e67". It also returns normal string values stored in a variant as a string, such as "my string". The application cannot reliably determine when a string is normal or contains embedded hexadecimal characters.
    • This setting forces all variant string values to be encoded as hexadecimal, making decoding string values predictable.
    • It overrides "binaryFormat" and always encodes variant strings as hexadecimal.
    • It removes the need to encode strings with JSON escape characters, such as \\ and \n. For example, this setting causes a variant value stored as "my string" to be returned as "6D7920737472696E67".

 

Example

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "athlete"
  },
  "responseOptions": {
    "stringFormat": "hex",
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "string",
    "variantFormat": "variantObject"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Implementation steps

  • Add the "stringFormat" property to the "responseOptions" property for all "getRecords…" actions except for "getRecordsUsingSql".
  • Add the "stringFormat" property to the "defaultResponseOptions" property in the "createSession" and "alterSession" actions.
    • It defines the default value for the "stringFormat" property for "getRecords…" actions.
  • Add the "stringFormat" property to services.json under the "jsonActionApiDefaults"."defaultResponseOptions" properties.
    • It defines the default value for the "stringFormat" property for all sessions.

Was this article helpful?

Give feedback about this article

Related Articles