rdrs2 · the RonDB REST API server

rdrs2: one C++ process serves REST, RonSQL, Rondis and TTL purging

The Go server of RonDB 21.04 was rewritten in C++ as rdrs2 in 24.10. Scans came in 25.10; batch writes and deletes and API 0.2.0 in 26.10.

code: storage/ndb/rest-server2 (config_structs_def.hpp: ServerPort 4406, NumThreads 64, ProbePort 4407, RonSQL NumThreads 16; MySQLRouter is myrouter, a testing tool) · CMakeLists.txt (Drogon) · notes: apis.md (history from release notes)

Endpoints · served under /0.1.0 and /0.2.0

REST endpoints: eleven, from a key read to SQL

0.1.0 returns errors as text; 0.2.0 as JSON objects with HTTP code, NDB and MySQL error codes. New clients should use 0.2.0.

code: rest-server2/server/src/constants.hpp (API_VERSION 0.1.0, API_VERSION_2 0.2.0, the *_PATH definitions) · rest-server2/CLAUDE.md (0.2.0 error format) · docs: rondb_rest_api.md (REST API)

pk-read · one row

pk-read: name the full primary key, and optionally the columns to return

POST /0.2.0/test_db/my_table/pk-read
{
  "filters": [
    {"column": "id0", "value": 0},
    {"column": "id1", "value": 0}
  ],
  "readColumns": [
    {"column": "col0"},
    {"column": "col1"}
  ],
  "operationId": "ABC123"
}

200 OK
{
  "operationId": "ABC123",
  "data": {
    "col0": 123,
    "col1": 456
  }
}

docs: rondb_rest_api.md (Primary Key Read Request and Response; dataReturnType left out, it only supports default) · code: rest-server2/server/src/config_structs_def.hpp (OperationIDMaxSize 256)

batch · many reads in one request

A batch is a list of pk-reads, each with its own table and answer

POST /0.2.0/batch
{
  "operations": [
    {
      "method": "POST",
      "relative-url": "db_1/table_1/pk-read",
      "body": { "filters": [ … ],
                "operationId": "1" }
    },
    {
      "method": "POST",
      "relative-url": "db_2/table_2/pk-read",
      "body": { "filters": [ … ],
                "operationId": "2" }
    }
  ]
}

docs: rondb_rest_api.md (Batched Primary Key) · code: rest-server2/server/src/config_structs_def.hpp (BatchMaxSize 128, 50–512) · db_operations/pk/pkr_operation.cpp (batches run in chunks of BatchMaxSize)

Writes · new in 26.10

batchwrite and batchdelete change rows by primary key

POST /0.2.0/batchwrite
{
  "operations": [
    { "method": "POST",
      "relative-url": "db/t/pk-write",
      "body": { "filters": [ … ],
                "writeColumns": [ … ] } },
    { "method": "POST",
      "relative-url": "db/t/pk-update", … },
    { "method": "POST",
      "relative-url": "db/t/pk-insert", … }
  ]
}

code: rest-server2/CLAUDE.md (Batch Write, Batch Delete, URL suffixes and NDB operations) · notes: apis.md (404 and 409)

scan · filters and index ranges

REST scan: a filter tree, an optional index range, and a limit

POST /0.1.0/test_db/t/scan
{ "limit": 10,
  "readColumns": [{"column": "pk"}, {"column": "val_1"}],
  "filters": { "op": "AND", "args": [
      { "op": "ISNOTNULL", "column": "content" },
      { "op": "CMP", "column": "pk",
        "cond": "GT", "value": 2 } ] },
  "index": { "name": "idx_val",
    "key_columns": ["val_1", "val_2"],
    "ranges": [ {
      "lower": {"values": [10, 100], "inclusive": true},
      "upper": {"values": [70, 700], … } } ] } }

docs: rest_scan_api.md (request shortened) · code: rest-server2 json_parser.cpp (two arguments, depth 32, 64 ranges) · config_structs_def.hpp (ScanTimingEnabled false, SlowScanThresholdUs 10000)

feature_store · Hopsworks feature views

feature_store: ask for a feature view by entity key, get the whole feature vector

POST /0.2.0/feature_store
{
  "featureStoreName": "fs",
  "featureViewName": "fraud_fv",
  "featureViewVersion": 1,
  "entries": { "cc_num": 4423 },
  "passedFeatures": { },
  "metadataOptions": { … }
}
→ { "features": [ … ],
    "status": "COMPLETE" }

code: rest-server2/server/src (featureStoreName, featureViewName, featureViewVersion, entries, passedFeatures, metadataOptions; FeatureStatus COMPLETE, MISSING, ERROR) · docs: rest_fs_bench.md · values are illustrations

Measured · one REST server

One REST server: hundreds of thousands of requests/s, millions of rows batched

Single requests take tens of microseconds at low load: 0.04 ms median for one feature group on one thread. Batching multiplies rows per request.

docs: rest_bench.md · rest_fs_bench.md (the rows quoted)

Health · for load balancers and Kubernetes

Health checks: a separate probe port answers even when REST threads are busy

GET /metrics exposes Prometheus metrics for dashboards.

code: rest-server2 (health_ctrl.cpp, probe_server.hpp, config_structs_def.hpp ProbePort 4407) · notes: apis.md

Security · and fair use

Security: API keys say who calls; rate limits keep one tenant from starving others

code: rest-server2/server/src/constants.hpp (x-api-key) · config_structs_def.hpp (CacheRefreshIntervalMS 180000, TLS) · ConfigInfo.cpp (ActivateRateLimits false) · docs: rondb_rate_limits_quotas.md

Sizing · the settings that matter

REST server sizing: enough CPUs per server; add servers to scale

The measurements above used about 16 CPUs per REST server. Run several behind a load balancer; Kubernetes can scale them on CPU (module 19).

code: rest-server2/server/src/config_structs_def.hpp · docs: rest_bench.md · rondb_helm.md

Recap · module 21

What to take away

• rdrs2: REST on 4406, probes on 4407, plus RonSQL, Rondis and TTL purging.
• pk-read and batch for reads; batchwrite and batchdelete for changes; scan with pushed filters.
• Use API 0.2.0: JSON errors with NDB and MySQL codes.
• feature_store returns a whole feature vector from cached view definitions.
• API keys, rate limits with 429, and several servers of about 16 CPUs each.

Next · 22 · RonSQL

RonDB training · 25 modules · you are at 21

Next · 22 · RonSQL