trustgraph/docs/apis/websocket.md

# 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
}
```