`"describeServices"`

The "describeServices" action returns one or more session objects that the logged-in account is authorized to view.

Things to know

When the "params" property is omitted, the "describeServices" action returns information about the current session and all other sessions directly created by the account.
Placeholder

Request examples

Minimal request example

Maximal request example

Response examples

Successful response example

Failure response example

`"params"`

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Property summary

Table 1. "params" property summaries

Property	Description	Default	Type	Limits (inclusive)
`"authTokens"`	contains one or more authorization token strings	`[]`	array	At least one `"authToken"`

`"result"`

The "result" property is a required object set by the server that contains the result of an action.

Things to know:

It is a required part of the jsonAction specification standard.
Its properties vary with each action.

Properties summary

Table 2. "result" property summaries

Property

Description

Type

Limits (inclusive)

"authToken"

signifies that the client is authenticated and authorized

string

Minimum length: 0

Maximum length: 255

"defaultBinaryFormat"

specifies the default value for the "binaryFormat" property, which tells the server how to parse binary data from the client when the binary format is not specified in the action request

string

"base64"

"hex"

"defaultDatabaseName"

specifies the default value of the "databaseName" property

string

Minimum length: 1

Maximum length: 64

"defaultOwnerName"

specifies the initial value of the "defaultOwnerName" property used by JSON APIs and FairCom's web application

string

Minimum length: 1

Maximum length: 64

"defaultResponseOptions"

specifies a default value for "responseOptions" that is used by default in all other action calls

object

One of the following:

"includeFields"

"excludeFields"

"includePaths"

"excludePaths"

"omit"

"numberFormat"

"dataFormat"

Note

"includeFields" and "excludeFields" are mutually exclusive

"includePaths" and "excludePaths" are mutually exclusive

"description"

describes an object for later identification

string

Minimum length: 0

Maximum length: 65,500

"idleConnectionTimeoutSeconds"

specifies the number of seconds that a session with no activity will stay open

integer

0 - 2147483647

"idleCursorTimeoutSeconds"

specifies the number of seconds to keep a cursor open

integer

0 - 2147483647

"username"

specifies the account name of a user or application

string

Minimum length: 1

Maximum length: 64

`"authToken"`

The "authToken" property signifies that the client is authenticated and authorized. It is required.

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.

`"defaultResponseOptions"`

The "defaultResponseOptions" property is a "responseOptions" object. It defines a default value for "responseOptions" that is used by default in all other action calls. It defaults to an empty object.

Things to know:

JSON NAV allows you to choose how your program detects errors. By default, all error properties are included in each response – unless you override this behavior as shown in the example.
The example omits the error object in all responses and omitting the error object makes it easier for statically typed languages, such as C, C++, Java, C#, and VB, because they prefer properties to always be present. To help these languages, the "errorCode", "errorMessage", and "errorData" properties are always present whether there is an error or not.

Example

"defaultResponseOptions": {
      "dataFormat": "objects",
      "numberFormat": "string",
      "binaryFormat": "hex"
    }

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

The "binaryFormat" property may occur inside "params", "responseOptions", and "result".
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:
- "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
    +
    /
    =
- "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

"params" and "responseOptions" as "hex" request example

This example shows how how the "binaryFormat" property can occur in the "params" and "responseOptions" properties and how the "value" property is a string value that contains a hexadecimal encoded binary value. To use these examples, you should first use FairCom's Data Explorer to create the "all_types" table, its indexes, and insert at least one record.

{
  "requestId": "1",
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "api": "db",
  "apiVersion": "1.0",
  "action": "getRecordsStartingAtKey",
  "params": {
    "databaseName": "ctreeSQL",
    "tableName": "all_types",
    "binaryFormat": "hex",
    "indexFilter": {
      "indexName": "fixed_binary_10bytes",
      "operator": "=",
      "indexFields": [
        {
          "fieldName": "fixed_binary_10bytes",
          "value": "FF00FF00000000000000"
        }
      ]
    }
  },
  "responseOptions": {
    "dataFormat": "objects",
    "binaryFormat": "hex"
  }
}

"params" as "base64" & "responseOptions" as "hex" request example

This example shows how the "binaryFormat" property can be set to different values in the "params" and "responseOptions" properties. This allows you to submit binary values in one encoding and retrieve binary values in another encoding.

{
  "requestId": "2",
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "api": "db",
  "apiVersion": "1.0",
  "action": "getRecordsStartingAtKey",
  "params": {
    "databaseName": "ctreeSQL",
    "tableName": "all_types",
    "binaryFormat": "base64",
    "indexFilter": {
      "indexName": "fixed_binary_10bytes",
      "operator": "=",
      "indexFields": [
        {
          "fieldName": "fixed_binary_10bytes",
          "value": "/wD/AAAAAAAAAA=="
        }
      ]
    }
  },
  "responseOptions": {
    "dataFormat": "objects",
    "binaryFormat": "base64"
  }
}

"binaryFormat" in "result" response example

This example shows that the server response always includes a "binaryFormat" property inside the "result" property. It indicates how it encoded binary values in the response. Note that this response has been edited for brevity.

{
    "authToken": "replaceWithAuthTokenFromCreateSession",
    "result": {
        "dataFormat": "objects",
        "binaryFormat": "base64",
        "fields": [],
        "data": [],
        "primaryKeyFields": ["id"],
        "changeIdField": "changeId",
        "moreRecords": false,
        "requestedRecordCount": 20,
        "returnedRecordCount": 4,
        "totalRecordCount": 4
    },
    "requestId": "1",
    "errorCode": 0,
    "errorMessage": ""
}

`"dataFormat"`

The "dataFormat" property is an optional, case-insensitive string enum that defines the format of the response in the "data" property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request and another occurs in a response. They all indicate how data is formatted.

"dataFormat" in the request inside "responseOptions" determines how the "data" property in the response is formatted.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.
Possible values include:
- "arrays"
  This causes the server to return results as an array of arrays, which is the 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 is the default and causes the server to automatically detect the format of the data in the "sourceData" property.
"dataFormat" in the response shows the client how the server formatted the "data" property.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

`"idleConnectionTimeoutSeconds"`

The "idleConnectionTimeoutSeconds" property is an optional integer from 0 to 2,147,483,647. It is the number of seconds that a session with no activity will stay open.

Thing to know:

Each time a session executes an operation, the session timer restarts.
A value of 0 keeps a session open indefinitely.

`"idleCursorTimeoutSeconds"`

The "idleCursorTimeoutSeconds" property is an optional integer from 0 to 2,147,483,647. It is the number of seconds to keep a cursor open.

Things to know:

Each time a cursor retrieves records, the cursor timer restarts.
A value of -1 keeps a cursor open indefinitely.
A value of 0 immediately closes a cursor after the current operation.

`"username"`

The "username" property is a required string from 1 to 64 bytes. It is the account name of a user or application.

Things to know:

It is required by the "createSession" action for authentication.
All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.
In JSON DB API and JSON Edge API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.
Unlike other property names, such as "databaseName", "username" is all lowercase.
A zero-length username is invalid.