API HTTP

namidb-server expone una API JSON-sobre-HTTP pequeña sobre el motor. Cuatro endpoints, un esquema de auth, un envelope.

Para arrancar el servidor, flags y modelo de concurrencia, consulta Servidor HTTP.

Rutas (v0)

Método	Path	Auth	Descripción
`GET`	`/v0/health`	público	Liveness + versión del manifest + epoch
`GET`	`/v0/version`	público	Versión del build del servidor
`POST`	`/v0/cypher`	bearer	Ejecuta una consulta Cypher (lectura o escritura)
`POST`	`/v0/admin/flush`	bearer	Fuerza un flush del memtable a SSTs L0

Autenticación

Los endpoints POST requieren Authorization: Bearer <token> donde <token> coincide con el flag --auth-token del servidor (o la env var NAMIDB_AUTH_TOKEN). Los endpoints GET (/v0/health, /v0/version) son públicos.

Si el servidor arranca sin un auth token, todas las requests se aceptan; el daemon imprime un warning ruidoso al boot y no debería estar expuesto al internet público.

`POST /v0/cypher`

Request

{
  "query": "MATCH (p:Person) WHERE p.age >= $min RETURN p.name AS name",
  "params": {"min": 18}
}

params es opcional. El string de consulta sigue el subset soportado.

Response de lectura

{
  "columns": ["name"],
  "rows": [{"name": "Alice"}, {"name": "Bob"}]
}

Las columnas siguen el orden de proyección del RETURN de la consulta, no el orden natural de claves del map de la fila.

Response de escritura

{
  "columns": ["a"],
  "rows": [{
    "a": {
      "_kind": "node",
      "id": "...",
      "label": "Person",
      "properties": {}
    }
  }],
  "write_outcome": {
    "nodes_created": 1,
    "edges_created": 0,
    "nodes_deleted": 0,
    "edges_deleted": 0,
    "properties_set": 0
  }
}

Las respuestas de escritura incluyen un objeto write_outcome con contadores por operación. Los contadores incrementan por operación del executor, no por cambio neto de estado.

Mapeo JSON ↔ Cypher

Cypher `RuntimeValue`	JSON
`Null`	`null`
`Bool`	`true` / `false`
`Integer`	number (i64)
`Float`	number (f64)
`String`	string
`Bytes`	base64 string
`Vector(f32)`	array de números
`List`	array
`Map`	object
`Date`	string de fecha ISO-8601
`DateTime` (UTC, microsegundos)	string de timestamp RFC-3339
`Node`	`{"_kind": "node", "id", "label", "properties"}`
`Rel`	`{"_kind": "rel", "edge_type", "src", "dst", "properties"}`
`Path`	array alternando objetos node / rel

Round-trip end-to-end con `curl`

TOKEN=$(openssl rand -hex 32)

namidb-server --store memory://demo --listen 127.0.0.1:8080 --auth-token "$TOKEN" &

# Health
curl -s http://127.0.0.1:8080/v0/health | jq .

# Create
curl -s -X POST http://127.0.0.1:8080/v0/cypher \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query": "CREATE (a:Person {name: \"Alice\", age: 30}) RETURN a.name AS name"}' \
  | jq .

# Read
curl -s -X POST http://127.0.0.1:8080/v0/cypher \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query": "MATCH (p:Person) RETURN p.name AS name, p.age AS age"}' \
  | jq .

`POST /v0/admin/flush`

Fuerza el flush inmediato del memtable a SSTs L0. Útil cuando --flush-interval 0s desactivó el loop en background y un sidecar está manejando la cadencia del flush.

curl -s -X POST http://127.0.0.1:8080/v0/admin/flush \
  -H "Authorization: Bearer $TOKEN"

En el roadmap

El README del servidor lista estos endpoints como planeados pero aún sin aterrizar:

/v0/cypher/stream — streaming NDJSON para result sets grandes.
/v0/cypher/arrow — body Arrow IPC para ingesta zero-copy en DataFrames.
/v0/metrics — exposición Prometheus (counters, histograma de latencia, tasas de hit del caché).

Siguientes pasos

Servidor HTTP — flags, env vars, modelo de concurrencia.
Bolt (drivers Neo4j) — cuando quieres un protocolo binario orientado a sesión en vez de REST.
Configuración — cada env var que el servidor lee.