API documentation (#221)

2026-04-25 00:16:23 +02:00 · 2024-12-28 16:59:11 +00:00 · 2024-12-28 16:59:11 +00:00 · 2d3802e001
commit 2d3802e001
parent 74ea3b8b96
13 changed files with 1163 additions and 20 deletions
--- a/docs/apis/api-triples-query.md
+++ b/docs/apis/api-triples-query.md
@ -0,0 +1,187 @@
+
+# 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
+
+
+
+
+
+
+
+