HTTP API Reference

pg_ripple_http is a standalone Rust binary that exposes the full pg_ripple feature set over HTTP. It supports the W3C SPARQL 1.1 Protocol, live subscription streams over Server-Sent Events, Datalog REST operations, PageRank, probabilistic reasoning, Arrow Flight bulk export, and administrative endpoints.

Start the service:

PG_RIPPLE_HTTP_PG_URL=postgresql://localhost/mydb \
PG_RIPPLE_HTTP_PORT=7878 \
PG_RIPPLE_HTTP_AUTH_TOKEN=mysecret \
pg_ripple_http

Authentication

All protected endpoints require a Bearer token. Read, write, admin, and metrics tokens can be separated with the corresponding environment variables; when a specialized token is unset, the main token is used for that class.

Authorization: Bearer <token>

Health endpoints are public. Metrics are public unless PG_RIPPLE_HTTP_METRICS_TOKEN is configured. All other endpoints are protected by their access class.

Configuration

Complete Endpoint Reference

Read and Write mean the endpoint calls the HTTP companion's read or write authentication check when PG_RIPPLE_HTTP_AUTH_TOKEN is configured. None means the endpoint is intentionally unauthenticated.

SPARQL Endpoints

GET /sparql

W3C SPARQL 1.1 Protocol query endpoint.

Query Parameters:

Accept header controls the result format:

Example:

curl -G "http://localhost:7878/sparql" \
  --data-urlencode 'query=SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10' \
  -H "Accept: application/sparql-results+json"

POST /sparql

Accepts the query either as an application/x-www-form-urlencoded body (form post) or as a raw application/sparql-query / application/sparql-update body.

Form body parameters: same as GET /sparql query parameters.

Example (SELECT):

curl -X POST http://localhost:7878/sparql \
  -H "Content-Type: application/sparql-query" \
  -d 'SELECT ?label WHERE { <https://example.org/Alice> rdfs:label ?label }'

Example (UPDATE, requires auth):

curl -X POST http://localhost:7878/sparql \
  -H "Content-Type: application/sparql-update" \
  -H "Authorization: Bearer $TOKEN" \
  -d 'INSERT DATA { <:Alice> rdfs:label "Alice" }'

POST /sparql/bindings

Execute a read-only SELECT, ASK, CONSTRUCT, or DESCRIBE query with one-row typed initial bindings. The request body is JSON; binding values use the W3C SPARQL Results JSON term shape and support uri and literal terms.

{
  "query": "SELECT ?s WHERE { ?s <https://example.org/email> ?email }",
  "bindings": {
    "email": {"type": "literal", "value": "alice@example.test"}
  },
  "prefix_mode": "strict",
  "timeout_ms": 1000
}

Use prefix_mode: "registered" to resolve undeclared prefixes from the governed registry. Query-local declarations take precedence. Binding payloads are validated before streaming begins; SPARQL Update, blank-node, RDF-star, and multi-row bindings are rejected.

The response uses the same content negotiation and streaming formats as POST /sparql/stream.

POST /sparql/stream

Explicit streaming compatibility alias. Results are delivered from the PostgreSQL row stream with natural HTTP backpressure.

Request: Same as POST /sparql.

Response Content-Type: application/sparql-results+json, text/csv, text/tab-separated-values, or application/n-triples, selected by Accept. JSON is a complete SPARQL Results JSON document, not JSON-Lines or SSE. XML, Turtle, and JSON-LD remain buffered on /sparql.

Example:

curl -X POST http://localhost:7878/sparql/stream \
  -H "Content-Type: application/sparql-query" \
  -H "Accept: application/sparql-results+json" \
  -d 'SELECT ?s ?p ?o WHERE { ?s ?p ?o }' \
  --no-buffer

RAG Endpoint

POST /rag

Execute a hybrid SPARQL + vector-similarity RAG retrieval query. The endpoint embeds the question, finds the nearest RDF entities by cosine similarity, and returns structured results with a plain-text context string suitable for use as an LLM prompt.

Content-Type: application/json

Request body:

{
  "question": "what treats headaches?",
  "sparql_filter": "?entity a <https://pharma.example/Drug>",
  "k": 5,
  "model": "text-embedding-3-small",
  "output_format": "jsonb"
}

Response (200 OK):

{
  "results": [
    {
      "entity_iri": "https://pharma.example/aspirin",
      "label": "aspirin",
      "context_json": {
        "label": "aspirin",
        "types": ["Drug", "NSAID"],
        "properties": [{"predicate": "treats", "object": "headache"}],
        "contextText": "aspirin. Type: NSAID, Drug."
      },
      "distance": 0.12
    }
  ],
  "context": "aspirin. Type: NSAID, Drug.\n\nibuprofen. Type: Drug."
}

The context field is a concatenated plain-text summary ready for use as an LLM system prompt.

JSON Mapping Writeback

POST /json-mapping/{name}/writeback

Synchronously write one RDF subject back to the relational table configured for the named JSON mapping. This calls pg_ripple.writeback_json_row(name, subject_iri) and requires write auth when authentication is enabled.

Content-Type: application/json

{
  "subject_iri": "https://example.com/contacts/c001"
}

Response (200 OK):

{
  "rows_affected": 1
}

Error mapping:

GET /json-mapping/{name}/writeback/status

Return queue depth, error count, and last processed timestamp for one mapping. This is a filtered HTTP view over pg_ripple.json_writeback_status() and requires read auth when authentication is enabled.

Response (200 OK):

{
  "mapping_name": "contacts",
  "pending": 0,
  "errors": 0,
  "last_error": null,
  "last_processed_at": null
}

GET /json-mapping/{name}/writeback/config

Return the validated relational target and writeback health for one mapping. The response mirrors pg_ripple.writeback_inspect() and requires read auth when authentication is enabled.

Response (200 OK):

{
  "target_schema": "public",
  "target_table": "contacts",
  "key_columns": ["contact_id"],
  "conflict_policy": "replace",
  "writeback_enabled": false,
  "trigger_count": 0,
  "queue_depth": 0
}

Arrow Flight Bulk Export

POST /flight/do_get

Bulk-export SPARQL query results as an Apache Arrow IPC record stream. Suitable for high-throughput extract pipelines (DuckDB, pandas, Spark).

Content-Type: application/json

Request body:

{
  "ticket": "eyJhbGciOiJIUzI1NiJ9...",
  "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o }"
}

Response: application/vnd.apache.arrow.stream — Arrow IPC stream.

Example (Python):

import requests, pyarrow as pa

# 1. Get a signed ticket from PostgreSQL
ticket = pg.execute("SELECT pg_ripple.arrow_flight_ticket('SELECT ?s ?p ?o WHERE { ?s ?p ?o }')")

# 2. Stream the Arrow IPC export
r = requests.post("http://localhost:7878/flight/do_get",
    json={"ticket": ticket},
    headers={"Authorization": f"Bearer {token}"},
    stream=True)

reader = pa.ipc.open_stream(r.raw)
table = reader.read_all()
print(table.to_pandas())

Streaming Subscriptions

GET /subscribe/{subscription_id}

Subscribe to a live SPARQL result stream via Server-Sent Events. The subscription_id is returned by pg_ripple.subscribe(query).

Response Content-Type: text/event-stream

Event types:

Example:

# Create subscription in PostgreSQL
psql -c "SELECT pg_ripple.subscribe('SELECT ?s ?p ?o WHERE { ?s ?p ?o }')"
-- Returns: sub_abc123

# Connect SSE stream
curl -N "http://localhost:7878/subscribe/sub_abc123" \
  -H "Accept: text/event-stream"

Datalog REST API

GET /datalog/rules

List all registered Datalog rule sets.

Response (200 OK):

[
  {"rule_set": "rdfs_closure", "rule_count": 13, "enabled": true},
  {"rule_set": "custom_rules", "rule_count": 5, "enabled": true}
]

POST /datalog/rules/{rule_set}/add

Add a Datalog rule to a rule set.

Content-Type: application/json

{
  "rule": "ancestor(?x, ?z) :- ancestor(?x, ?y), parent(?y, ?z).",
  "enabled": true
}

Response (200 OK):

{"rule_id": "rule_42", "rule_set": "custom_rules"}

POST /datalog/infer/{rule_set}

Run forward-chaining inference for a rule set.

Content-Type: application/json

{
  "graph": "https://example.org/graph1",
  "max_iterations": 100,
  "dry_run": false
}

Response (200 OK):

{
  "derived_count": 847,
  "iterations": 3,
  "elapsed_ms": 42,
  "stratification_order": ["base_rules", "closure_rules"]
}

POST /datalog/infer/{rule_set}/wfs

Run well-founded semantics inference. Returns three-valued results (true / false / undefined) for recursive rules with negation.

POST /datalog/infer/{rule_set}/demand

Goal-directed magic-sets inference. Only derives facts relevant to a specific query goal.

Content-Type: application/json

{
  "goal": "ancestor(<:Alice>, ?z)",
  "graph": "https://example.org/graph1"
}

POST /datalog/query/{rule_set}

Run a single Datalog goal query against a materialized rule set without modifying the store.

Content-Type: application/json

{
  "goal": "ancestor(<:Alice>, ?z)",
  "limit": 100
}

Response (200 OK):

{
  "results": [
    {"?z": "<https://example.org/Bob>"},
    {"?z": "<https://example.org/Carol>"}
  ],
  "total": 2
}

GET /datalog/constraints

Check all constraint rules across all rule sets.

Response (200 OK):

{
  "violations": [
    {
      "rule_set": "integrity_rules",
      "constraint": "uniqueness_violation",
      "violating_bindings": [{"?x": "<:entity1>"}]
    }
  ],
  "total_violations": 1
}

GET /datalog/stats/cache

Returns rule plan cache hit/miss statistics.

GET /datalog/stats/tabling

Returns tabling cache occupancy and eviction statistics.

PageRank API

POST /pagerank/run

Start a PageRank computation job.

Content-Type: application/json

{
  "graph": "https://example.org/graph1",
  "edge_predicates": ["schema:knows", "schema:worksFor"],
  "damping": 0.85,
  "max_iterations": 100,
  "convergence_delta": 0.0001
}

Response (200 OK):

{
  "job_id": "pr_20250503_001",
  "status": "running",
  "started_at": "2025-05-03T12:00:00Z"
}

GET /pagerank/status

Poll the status of the most recent PageRank job.

Response:

{
  "job_id": "pr_20250503_001",
  "status": "completed",
  "iterations": 47,
  "elapsed_ms": 1204,
  "node_count": 50000,
  "edge_count": 250000
}

GET /pagerank/export

Export PageRank scores as JSON or CSV.

Query parameters:

Response (200 OK, JSON):

{
  "scores": [
    {"iri": "https://example.org/Alice", "score": 0.0423, "rank": 1},
    {"iri": "https://example.org/Bob", "score": 0.0381, "rank": 2}
  ],
  "total": 50000
}

GET /pagerank/explain/{node_iri}

Explain the PageRank score for a specific node, showing top contributing in-edges.

Path parameter: node_iri — URL-encoded IRI.

Response:

{
  "iri": "https://example.org/Alice",
  "score": 0.0423,
  "rank": 1,
  "top_contributors": [
    {"from_iri": "https://example.org/Bob", "edge_weight": 0.012},
    {"from_iri": "https://example.org/Carol", "edge_weight": 0.009}
  ]
}

POST /centrality/run

Compute centrality metrics (degree, betweenness, Katz).

Content-Type: application/json

{
  "graph": "https://example.org/graph1",
  "metrics": ["degree", "katz"],
  "katz_alpha": 0.01
}

POST /pagerank/find-duplicates

Find near-duplicate nodes by PageRank score similarity and graph structure.

Confidence / Probabilistic API

POST /confidence/load

Load triples with associated confidence scores.

Content-Type: application/json

{
  "triples": [
    {
      "subject": "https://example.org/Alice",
      "predicate": "rdf:type",
      "object": "schema:Person",
      "confidence": 0.95,
      "graph": "https://example.org/g1"
    }
  ]
}

Response (200 OK):

{"inserted": 1, "updated": 0}

GET /confidence/shacl-score

Get SHACL soft-validation confidence scores for shapes.

Query parameters:

GET /confidence/shacl-report

Get a full SHACL validation report with confidence scores per constraint.

POST /confidence/vacuum

Vacuum stale confidence score rows from _pg_ripple.confidence.

Administrative Endpoints

GET /health

Returns {"status": "ok"} when the service is running and the database connection pool is healthy.

Response: 200 OK — {"status": "ok"} Response: 503 Service Unavailable — database unreachable.

GET /health/ready

Kubernetes-compatible readiness probe. Checks that the PostgreSQL connection pool has at least one available connection.

GET /metrics

Prometheus-format metrics. No authentication required.

Key metrics:

GET /metrics/extension

Extension-internal Prometheus metrics sourced directly from the pg_ripple extension within PostgreSQL.

GET /void

Returns a VoID (Vocabulary of Interlinked Datasets) dataset description, summarizing the RDF store contents: triple counts, predicate frequencies, and class distributions.

Accept: text/turtle or application/ld+json

GET /service

Returns a SPARQL 1.1 Service Description document describing the endpoint's capabilities.

Accept: text/turtle or application/ld+json

GET /openapi.yaml

Returns the full OpenAPI 3.1 specification for the pg_ripple_http API.

GET /explorer

Web-based SPARQL explorer UI — an embedded query editor with syntax highlighting, result table, and endpoint configuration.

Error Responses

All error responses use a consistent JSON envelope:

{
  "error": "PT440",
  "message": "query exceeds maximum algebra depth (256)",
  "hint": "Simplify the query or raise pg_ripple.sparql_max_algebra_depth"
}

Security

• Bearer token authentication controls mutating endpoints
• SSRF protection: federation SERVICE endpoints are checked against federation_endpoint_policy
• SQL injection prevention: all queries use parameterized PostgreSQL SPI
• Arrow Flight tickets are HMAC-SHA256 signed; set pg_ripple.arrow_flight_secret
• Rate limiting: per-IP, configurable via PG_RIPPLE_HTTP_RATE_LIMIT
• HTTPS termination should be handled by a reverse proxy (nginx, Caddy, Traefik)
• Never expose PG_RIPPLE_HTTP_AUTH_TOKEN in URLs or logs