`"pingSession"`

Abstract

pingSession verifies that a FairCom server or session is listening and responding. It helps troubleshoot connectivity and session viability.

The "pingSession" action returns a response with the "errorCode" property set to 0 when successful. Otherwise, the server will either return no response or return an error response wit the "errorCode" property set to a non-zero value.

Things to know

"pingSession" can be used to determine if a server instance is working.
If the "authToken" property is present in the request, the server will extend the life of the session and the response will contain no error.
When the "authToken" is not valid, the response will contain an error.

Request examples

Minimal request example

{
  "api": "admin",
  "action": "pingSession"
}

Maximal request example

{
  "requestId": "2",
  "authToken": "anAuthorizationTokenFromTheServer",
  "api": "admin",
  "action": "pingSession",
  "params": {
  },
  "responseOptions": {
  },
  "apiVersion": "1.0",
  "debug": "max"
}

Response examples

Successful response example

This example shows the database server is responding and that the "authToken" property represents an active session.

 {
    "result": {},
    "requestId": "00000047",
    "errorCode": 0,
    "errorMessage": ""
}

Failed inactive session response example

When there is an inactive session "pingSession" returns a non-error response. It shows the FairCom server is responding and that the "authToken" property represents an active session.

{
  "schema": "faircom.com/schemas/db",
  "requestId": "2",
  "authToken": "12345678901234567890fakeAuthToken64bytes123456789012345678901234",
  "api": "db",
  "apiVersion": "1.0",
  "action": "pingSession",
  "params": {},
  "result": {},
  "debugInfo": {},
  "errorCode": -1,
  "errorMessage": "authToken invalid or expired."
}

Unsupported `"authToken"` response example

This example returns an error that indicates the database server is responding but that the "authToken" property is expired because it does not represent an active session.

{
  "authToken": "invalidAuthtoken",
  "requestId": "00000003",
  "debugInfo": {
    "request": {
      "authToken": "invalidAuthtoken",
      "api": "admin",
      "action": "pingSession",
      "params": {},
      "apiVersion": "1.0",
      "requestId": "00000003",
      "responseOptions": {},
      "debug": "max"
    }
  },
  "errorCode": 12031,
  "errorMessage": "'authToken' does not match any existing session. Use a valid 'authToken' or use 'createSession' to create a valid 'authToken'."
}

"pingSession"