From 14907b1f1b9c873e0a7c0b0e3d6b0f6b1e87e08e Mon Sep 17 00:00:00 2001
From: Cyber MacGeddon <cybermaggedon@gmail.com>
Date: Sat, 28 Dec 2024 16:33:41 +0000
Subject: [PATCH] More API doc hacking

---
 docs/apis/api-triples-query.md | 184 ++++++++++++++++++++++++++++++++-
 1 file changed, 182 insertions(+), 2 deletions(-)

diff --git a/docs/apis/api-triples-query.md b/docs/apis/api-triples-query.md
index faa6f7ca..6e096a56 100644
--- a/docs/apis/api-triples-query.md
+++ b/docs/apis/api-triples-query.md
@@ -1,7 +1,187 @@
-{"id":"qgzw1287vfjc8wsk-4","service":"triples-query","request":{"s":{"v":"http://trustgraph.ai/e/space-station-modules","e":true},"p":{"v":"http://www.w3.org/2000/01/rdf-schema#label","e":true},"limit":1}}
+
+# TrustGraph Triples Query API
+
+This is a service which queries the knowledge graph for triples ("facts").
+
+## Request/response
+
+### Request
+
+The request contains the following fields:
+- `s`: Optional, if included specifies a match for the subject part of a
+  triple.
+- `p`: Optional, if included specifies a match for the subject part of a
+  triple.
+- `o`: Optional, if included specifies a match for the subject part of a
+  triple.
+- `limit`: Optional, if included specifies the maximum number of triples to
+  return.  If not specified, an arbitrary value is used.
+
+Returned triples will match all of `s`, `p` and `o` where provided.
+
+### Response
+
+The request contains the following fields:
+- `response`: A list of triples.
+
+Each triple contains `s`, `p` and `o` fields describing the
+subject, predicate and object part of each triple.
+
+Each triple element uses the same schema:
+- `value`: the entity URI or literal value depending on whether this is
+  graph entity or literal value.
+- `is_uri`: A boolean value which is true if this is a graph entity i.e.
+  `value` is a URI, not a literal value.
+
+## REST service
+
+The REST service accepts a request object containing the `s`, `p`, `o`
+and `limit` fields.
+The response is a JSON object containing the `response` field.
+
+To reduce the size of the JSON, the graph entities are encoded as an
+object with `value` and `is_uri` mapped to `v` and `e` respectively.
+
+e.g.
+
+This example query matches triples with a subject of
+`http://trustgraph.ai/e/space-station-modules` and a predicate of
+`http://www.w3.org/2000/01/rdf-schema#label`.  This predicate
+represents the RDF schema 'label' relationship.
+
+The response is a single triple - the `o` element contains the
+literal "space station modules" which is the label for
+`http://trustgraph.ai/e/space-station-modules`.
+
+Request:
+```
+{
+    "id": "qgzw1287vfjc8wsk-4",
+    "service": "triples-query",
+    "request": {
+        "s": {
+            "v": "http://trustgraph.ai/e/space-station-modules",
+            "e": true
+        },
+        "p": {
+            "v": "http://www.w3.org/2000/01/rdf-schema#label",
+            "e": true
+        },
+        "limit": 5
+    }
+}
+```
+
+Response:
+
+```
+{
+    "response": [
+        {
+            "s": {
+                "v": "http://trustgraph.ai/e/space-station-modules",
+                "e": true
+            },
+            "p": {
+                "v": "http://www.w3.org/2000/01/rdf-schema#label",
+                "e": true
+            },
+            "o": {
+                "v": "space station modules",
+                "e": false
+            }
+        }
+    ]
+}
+```
+
+## Websocket
+
+Requests have a `request` object containing the `system` and
+`prompt` fields.
+Responses have a `response` object containing `response` field.
+
+To reduce the size of the JSON, the graph entities are encoded as an
+object with `value` and `is_uri` mapped to `v` and `e` respectively.
+
+e.g.
+
+Request:
+
+```
+{
+    "id": "qgzw1287vfjc8wsk-4",
+    "service": "triples-query",
+    "request": {
+        "s": {
+            "v": "http://trustgraph.ai/e/space-station-modules",
+            "e": true
+        },
+        "p": {
+            "v": "http://www.w3.org/2000/01/rdf-schema#label",
+            "e": true
+        },
+        "limit": 5
+    }
+}
+```
+
+Responses:
+
+```
+{
+    "id": "qgzw1287vfjc8wsk-4",
+    "response": {
+        "response": [
+            {
+                "s": {
+                    "v": "http://trustgraph.ai/e/space-station-modules",
+                    "e": true
+                },
+                "p": {
+                    "v": "http://www.w3.org/2000/01/rdf-schema#label",
+                    "e": true
+                },
+                "o": {
+                    "v": "space station modules",
+                    "e": false
+                }
+            }
+        ]
+    },
+    "complete": true
+}
+```
+
+## Pulsar
+
+The Pulsar schema for the Triples Query API is defined in Python code here:
+
+https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/schema/graph.py
+
+Default request queue:
+`non-persistent://tg/request/triples-query`
+
+Default response queue:
+`non-persistent://tg/response/triples-query`
+
+Request schema:
+`trustgraph.schema.TriplesQueryRequest`
+
+Response schema:
+`trustgraph.schema.TriplesQueryResponse`
+
+## Pulsar Python client
+
+The client class is
+`trustgraph.clients.TriplesQueryClient`
+
+https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/clients/triples_query_client.py
+
+
+
 
 
 
-{"id": "qgzw1287vfjc8wsk-4", "response": {"response": [{"s": {"v": "http://trustgraph.ai/e/space-station-modules", "e": true}, "p": {"v": "http://www.w3.org/2000/01/rdf-schema#label", "e": true}, "o": {"v": "space station modules", "e": false}}]}, "complete": true}