TrustGraph websocket overview

The websocket service is provided by the api-gateway service on port 8088.

URL

Depending on how the service is hosted, the websocket is invoked on this URL on api-gateway:

/api/v1/socket

When hosted using docker compose, you can access the service at ws://localhost:8088/api/v1/socket

Request

A request message is a JSON message containing 3/4 fields:

• id: A unique ID which is used to correlate requests and responses. You should make sure it is unique.
• service: The name of the service to invoke.
• request: The request body which is passed to the service - this is defined in the API documentation for that service.
• flow: Some APIs are supported by processors launched within a flow, are are dependent on a flow running. For such APIs, the flow identifier needs to be provided.

e.g.

{
    "id": "qgzw1287vfjc8wsk-1",
    "service": "graph-rag",
    "flow": "default",
    "request": {
        "query": "What does NASA stand for?"
    }
}

Response

A response message is JSON encoded, and may contain the following fields:

• id: This is the same value provided on the request and shows which request this response is returned for.
• error: If an error occured, this field is provided, and provides an error message.
• response: For a non-error case, this provides a response from the service - the response structure depends on the service invoked. It is not provided if the error field is provided.
• complete: A boolean value indicating whether this response is the final response from the service. If set to false, the response values are intermediate values. It is not provided if the error field is provided.

An error response completes a request - no further responses will be provided.

e.g.

{
    "id": "qgzw1287vfjc8wsk-1",
    "response": {
        "response": "National Aeronautics and Space Administration."
    },
    "complete": true
}

Multi-part response

For a multi-part response, a number of responses are provided with the same ID until the final message which has the complete field set to true.

Note that multi-part responses are a feature of the websocket API which the request/response nature of the REST API is not able to provide.

e.g.

Request:

{
    "id": "blrqotfefnmnh7de-20",
    "service": "agent",
    "flow": "default",
    "request": {
        "question": "What does NASA stand for?"
    }
}

Responses:

{
    "id": "blrqotfefnmnh7de-20",
    "response": {
        "thought": "I need to query a knowledge base"
    },
    "complete": false
}

{
    "id": "blrqotfefnmnh7de-20",
    "response": {
        "observation": "National Aeronautics and Space Administration."
    },
    "complete": false
}

{
    "id": "blrqotfefnmnh7de-20",
    "response": {
        "thought": "I now know the final answer"
    },
    "complete": false
}

{
    "id": "blrqotfefnmnh7de-20",
    "response": {
        "answer": "National Aeronautics and Space Administration"
    },
    "complete": true
}