Questions about Rama 1.1.0 Java module REST APIs

[Ali ARGÜN]

Hi rama people,

We’re building a small “Curiosity Agent" minimal node on macOS and have pinned our build to the Maven coordinate `com.rpl:rama:1.1.0`, pulled from the Nexus repo listed in your docs (“Downloads, Maven, and local development”: https://redplanetlabs.com/docs/~/downloads-maven-local-dev.html — accessed 2025‑10‑09). Gradle 9.1 + Homebrew OpenJDK 25 are working well, and the module compiles.

While wiring the Java side we ran into a gap in the public REST helpers. In older examples we used `ai.redplanetlabs.rama.rest.RestServer` and `@RestTopology`. In 1.1.0 we don’t see equivalents under `com.rpl.rama.*`. After re-reading Tutorial 1 (“First module”: https://redplanetlabs.com/docs/~/tutorial1.html — accessed 2025‑10‑09) and the surrounding docs, we still have a few questions:

1. **REST surface:** Is there a supported successor to `RestServer` / `@RestTopology` in 1.1.x? Or is the recommended pattern to expose Rama functionality only via Query topologies and have an external HTTP gateway handle REST?
2. **Current Java entry points:** We now implement modules with `RamaModule#define(Setup, Topologies)`, declare depots via `setup.declareDepot("*name", Depot.random())`, build stream ETLs through `topologies.stream(...)`, and use `Ops` helpers. For local testing we launch with `com.rpl.rama.test.InProcessCluster` and `LaunchConfig`. Are these the canonical Java entry points for 1.1.x, or is there a more idiomatic skeleton/example we should follow?
3. **Health checks:** For a simple “status/health” endpoint, would you suggest exposing a Query topology (invoked by an external REST gateway) or some other pattern available in 1.1.x?

Any pointers or sample code would be greatly appreciated.

Thanks!

Ali Argün

[Nathan Marz]

Answers inline.

On Wed, Oct 8, 2025 at 10:28 PM Ali ARGÜN <argu...@gmail.com> wrote:

Hi rama people,

We’re building a small “Curiosity Agent" minimal node on macOS and have pinned our build to the Maven coordinate `com.rpl:rama:1.1.0`, pulled from the Nexus repo listed in your docs (“Downloads, Maven, and local development”: https://redplanetlabs.com/docs/~/downloads-maven-local-dev.html — accessed 2025‑10‑09). Gradle 9.1 + Homebrew OpenJDK 25 are working well, and the module compiles.

While wiring the Java side we ran into a gap in the public REST helpers. In older examples we used `ai.redplanetlabs.rama.rest.RestServer` and `@RestTopology`. In 1.1.0 we don’t see equivalents under `com.rpl.rama.*`. After re-reading Tutorial 1 (“First module”: https://redplanetlabs.com/docs/~/tutorial1.html — accessed 2025‑10‑09) and the surrounding docs, we still have a few questions:

I'm not sure what you're referring to with `ai.redplanetlabs.rama.rest.RestServer` and `@RestTopology`. Those have never been APIs in Rama. 

 

1. **REST surface:** Is there a supported successor to `RestServer` / `@RestTopology` in 1.1.x? Or is the recommended pattern to expose Rama functionality only via Query topologies and have an external HTTP gateway handle REST?

Rama's REST API is documented here. It lets you use most of Rama's functionality, with a few limitations, by communicating with the Conductor/Supervisors over HTTP. You can use query topologies with Rama's REST API.

 

2. **Current Java entry points:** We now implement modules with `RamaModule#define(Setup, Topologies)`, declare depots via `setup.declareDepot("*name", Depot.random())`, build stream ETLs through `topologies.stream(...)`, and use `Ops` helpers. For local testing we launch with `com.rpl.rama.test.InProcessCluster` and `LaunchConfig`. Are these the canonical Java entry points for 1.1.x, or is there a more idiomatic skeleton/example we should follow?

Yes, those are the correct entry points. This project has lots of examples of using Rama's Java API (as well as an associated blog post with each module).

 

3. **Health checks:** For a simple “status/health” endpoint, would you suggest exposing a Query topology (invoked by an external REST gateway) or some other pattern available in 1.1.x?

That's a reasonably lightweight way to check that the module is functional. I would have the query topology do a .allPartition so that its success relies on being able to reach every leader task thread, something like:

topologies.query("healthCheck).out("*res")

                .allPartition()

                .originPartition()

                .agg(Aggs.count()).out("*count")

                .each(Ops.IDENTITY, "healthy").out("*res");

 

Any pointers or sample code would be greatly appreciated.

Thanks!

Ali Argün

--
You received this message because you are subscribed to the Google Groups "rama-user" group.
To unsubscribe from this group and stop receiving emails from it, send an email to rama-user+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/rama-user/a5fc429d-d5ec-40bf-b5e9-c4335e0a9597%40Spark.