Skip to main content

jsonAction protocol

Standard message pattern for the JSON DB API


FairCom JSON DB APIhas a standard request-response message pattern.

The JSON DB API uses a request-response pattern that works over any communications protocol. FairCom has implemented the JSON DB API to work over HTTP.

The typical message pattern is as follows:
  1. The client logs into the server and creates a session using the JSON Admin API "createSession" action. The server sends back an Authorization Token called "authToken" that unique identifies the session. The client includes this information in all subsequent messages to the server so the server can authorize client requests.

  2. The client sends request messages to the FairCom server.

  3. The server returns response messages to the client.

Things to know:
  • All messages are encoded as JSON.

  • The structure of each message follows the design specified by jsonAction specification.


    The jsonAction specification allows additional properties to be added by an API. FairCom has added additional properties where they are needed. For example, "responseOptions" supports new "includeFields" and "excludeFields" properties that include and exclude database fields from query results.

  • To support asynchronous communication, such as WebSocket and MQTT:

    • The client adds a unique "requestId" property to each request message to allow the client to match a request to a response. The client can assign any JSON value to "requestId" and the server includes the "requestId" and its value in the response message.

    • A client can create multiple sessions with the server to process multiple requests in parallel. A client application can use the combination of "authToken" and "requestId" to uniquely identify each message.

  • FairCom's JSON APIs are stateful because a stateful connection is necessary for data processing tasks, such as retrieving the next set of data from a query or running another step in an ACID transaction.