APIs and surfaces

Cyoda exposes three distinct API surfaces. Picking the right one for the job matters; the surfaces are not equivalent, and each carries different guarantees.

Three surfaces

• REST — the default surface for user-facing clients and administrative operations. CRUD over entities, search, workflow invocations, schema management, dashboards.
• gRPC — the surface for compute. External processors and criteria services connect to the platform over gRPC, receive work, and return results. Supports bidirectional streaming.
• Trino SQL — the surface for analytics. Cross-entity queries, reporting, JDBC connections, BI tools. Queries run against a Trino catalogue that projects entities into virtual SQL tables.

Which surface, when?

• Building a UI, an admin tool, or a sync integration? REST.
• Writing a processor or criterion that runs against transitions? gRPC.
• Running analytics, reports, or ad-hoc queries across many entities? Trino SQL.

All three surfaces are backed by the same entity store. A transition recorded via REST is visible to gRPC compute nodes and queryable through Trino, with the same audit trail behind it.

REST: humans and services that speak to the platform

Use REST when the call represents a user or service interacting with the platform as a whole: creating an order, searching for customers, reading audit history, managing a workflow definition. This is the surface your front-end, your admin tooling, and most external integrations will use.

REST is synchronous, authenticated with OAuth 2.0 bearer tokens, and versioned. The full endpoint catalogue lives in the API reference.

gRPC: external processors that speak for the platform

Use gRPC when your code is a compute node acting on behalf of a workflow transition. Processors and criteria attached to a transition call out to external services over gRPC; those services stream work units back to the platform.

Prefer gRPC for compute over implementing processors as REST callbacks. Three reasons:

1. Audit hygiene. Every gRPC call is recorded against the transition that invoked it, inside the platform’s audit trail. REST callouts cannot reconstruct that association reliably.
2. Authorization is simpler. The platform brokers the identity and scopes passed to the compute node; you don’t have to manage credentials between the platform and your processor independently.
3. Bidirectional streaming. High-throughput ingest and transformation workloads benefit from streaming both ways; REST cannot.

For how to implement a compute node, see Build → client compute nodes.

Trino SQL: cross-entity analytics

Upcoming

Trino SQL is on the roadmap and not yet available in cyoda-go at this release. The section below documents the planned surface; names and shapes may change before release.

Use Trino when the question is analytical — joins across entity types, aggregates, reporting, time-series. Every entity model is projected into a set of virtual SQL tables; nested arrays and objects expand into separate tables so relational queries remain natural.

Typical uses:

• Ad-hoc analysis against live data in a notebook or BI tool.
• Scheduled reports that aggregate entities across a tenant.
• Historical queries using the point_time column for as-of reads.

The table generation rules, data-type mappings, JDBC connection patterns, and handling of polymorphic fields are in the Trino SQL reference. For the Build-side quickstart — connection recipe, first query, performance notes — see Analytics with SQL.