API documentation (#221)

docs/apis/websocket.md

@@ -0,0 +1,136 @@
+
+# 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 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.
+
+e.g.
+
+```
+{
+    "id": "qgzw1287vfjc8wsk-1",
+    "service": "graph-rag",
+    "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",
+    "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
+}
+```
+