Skip to main content

"pingSession" (jsonAction)

Identify if there are errors in a FairCom server instance

Use the "pingSession" action to determine if the JSON action API is working. You can include an "authToken" to determine if a specific session is active and to keep it alive.

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

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

Links: Concepts | Tutorials | FAQs

Request examples

Minimal

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

Maximal

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

Response examples

Success

This example shows the JSON action service is working. If the request contains an "authToken", a successful response also indicates the "authToken" represents an active session.

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

Unsuccessful response when the request contains an invalid "authToken"

This example returns an error indicating the "authToken" property does not represent an active session. If the service does not respond, the JSON action service is not running.

{
  "authToken": "invalidAuthToken",
  "errorCode": 12031,
  "errorMessage": "'authToken' does not match any existing session. Use a valid 'authToken' or use 'createSession' to create a valid 'authToken'."
}

Optional properties

"authToken"

The "authToken" property signifies that the client is authenticated and authorized. It is required except in "pingSession" and "createSession". For "pingSession" and "createSession" it defaults to an empty string.

The server generates a unique authentication token in response to "createSession". Clients must include it in all subsequent requests. If the client does not supply a valid "authToken", the server returns error 12031.

You can create a permanent "authToken" by setting the "permanentSession" property to true when you create a session. A permanent "authToken" works like an API key and does not expire.

The "pingSession" JSON action verifies if a FairCom server instance and its JSON action API are operational. It indicates success by returning an errorCode of 0 and errors with a non-zero errorCode. The action can also validate and maintain a session's activity when used with an "authToken".

API actions
JSON ADMIN API
jsonAction
admin session
pingSession
pingSessions
pingsSession
pingsSessions
ping session
check server
check session
test session
session validation
session keep-alive
server instance verification
maintain session
keep session active
activate session
session verification