Update docs for API/CLI changes in 1.0 (#420)

* Update some API basics for the 0.23/1.0 API change
2026-04-25 08:26:21 +02:00 · 2025-07-03 14:58:29 +01:00 · 2025-07-03 14:58:29 +01:00 · cc224e97f6
commit cc224e97f6
parent b1a546e4d2
69 changed files with 19981 additions and 407 deletions
--- a/docs/apis/api-config.md
+++ b/docs/apis/api-config.md
@ -0,0 +1,261 @@
+# TrustGraph Config API
+
+This API provides centralized configuration management for TrustGraph components.
+Configuration data is organized hierarchically by type and key, with support for
+persistent storage and push notifications.
+
+## Request/response
+
+### Request
+
+The request contains the following fields:
+- `operation`: The operation to perform (`get`, `list`, `getvalues`, `put`, `delete`, `config`)
+- `keys`: Array of ConfigKey objects (for `get`, `delete` operations)
+- `type`: Configuration type (for `list`, `getvalues` operations)
+- `values`: Array of ConfigValue objects (for `put` operation)
+
+### Response
+
+The response contains the following fields:
+- `version`: Version number for tracking changes
+- `values`: Array of ConfigValue objects returned by operations
+- `directory`: Array of key names returned by `list` operation
+- `config`: Full configuration map returned by `config` operation
+- `error`: Error information if operation fails
+
+## Operations
+
+### PUT - Store Configuration Values
+
+Request:
+```json
+{
+    "operation": "put",
+    "values": [
+        {
+            "type": "test",
+            "key": "key1",
+            "value": "value1"
+        }
+    ]
+}
+```
+
+Response:
+```json
+{
+    "version": 123
+}
+```
+
+### GET - Retrieve Configuration Values
+
+Request:
+```json
+{
+    "operation": "get",
+    "keys": [
+        {
+            "type": "test",
+            "key": "key1"
+        }
+    ]
+}
+```
+
+Response:
+```json
+{
+    "version": 123,
+    "values": [
+        {
+            "type": "test",
+            "key": "key1",
+            "value": "value1"
+        }
+    ]
+}
+```
+
+### LIST - List Keys by Type
+
+Request:
+```json
+{
+    "operation": "list",
+    "type": "test"
+}
+```
+
+Response:
+```json
+{
+    "version": 123,
+    "directory": ["key1", "key2", "key3"]
+}
+```
+
+### GETVALUES - Get All Values by Type
+
+Request:
+```json
+{
+    "operation": "getvalues",
+    "type": "test"
+}
+```
+
+Response:
+```json
+{
+    "version": 123,
+    "values": [
+        {
+            "type": "test",
+            "key": "key1",
+            "value": "value1"
+        },
+        {
+            "type": "test",
+            "key": "key2",
+            "value": "value2"
+        }
+    ]
+}
+```
+
+### CONFIG - Get Entire Configuration
+
+Request:
+```json
+{
+    "operation": "config"
+}
+```
+
+Response:
+```json
+{
+    "version": 123,
+    "config": {
+        "test": {
+            "key1": "value1",
+            "key2": "value2"
+        }
+    }
+}
+```
+
+### DELETE - Remove Configuration Values
+
+Request:
+```json
+{
+    "operation": "delete",
+    "keys": [
+        {
+            "type": "test",
+            "key": "key1"
+        }
+    ]
+}
+```
+
+Response:
+```json
+{
+    "version": 124
+}
+```
+
+## REST service
+
+The REST service is available at `/api/v1/config` and accepts the above request formats.
+
+## Websocket
+
+Requests have a `request` object containing the operation fields.
+Responses have a `response` object containing the response fields.
+
+Request:
+```json
+{
+    "id": "unique-request-id",
+    "service": "config",
+    "request": {
+        "operation": "get",
+        "keys": [
+            {
+                "type": "test",
+                "key": "key1"
+            }
+        ]
+    }
+}
+```
+
+Response:
+```json
+{
+    "id": "unique-request-id",
+    "response": {
+        "version": 123,
+        "values": [
+            {
+                "type": "test",
+                "key": "key1",
+                "value": "value1"
+            }
+        ]
+    },
+    "complete": true
+}
+```
+
+## Pulsar
+
+The Pulsar schema for the Config API is defined in Python code here:
+
+https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/config.py
+
+Default request queue:
+`non-persistent://tg/request/config`
+
+Default response queue:
+`non-persistent://tg/response/config`
+
+Request schema:
+`trustgraph.schema.ConfigRequest`
+
+Response schema:
+`trustgraph.schema.ConfigResponse`
+
+## Python SDK
+
+The Python SDK provides convenient access to the Config API:
+
+```python
+from trustgraph.api.config import ConfigClient
+
+client = ConfigClient()
+
+# Put a value
+await client.put("test", "key1", "value1")
+
+# Get a value
+value = await client.get("test", "key1")
+
+# List keys
+keys = await client.list("test")
+
+# Get all values for a type
+values = await client.get_values("test")
+```
+
+## Features
+
+- **Hierarchical Organization**: Configuration organized by type and key
+- **Versioning**: Each operation returns a version number for change tracking
+- **Persistent Storage**: Data stored in Cassandra for persistence
+- **Push Notifications**: Configuration changes pushed to subscribers
+- **Multiple Access Methods**: Available via Pulsar, REST, WebSocket, and Python SDK