Skip to main content
Your Restate handler can call other handlers in three ways:
To call a service from an external application, see the HTTP, Kafka, or SDK Clients documentation.
Why use Restate for service communication?

​
Generating service clients

The Restate Java SDK automatically generates clients for each of your services when you build the project. If you don’t see the generated clients, make sure you added the code generator and have built the project with ./gradlew build or mvn compile exec:java.

​
Request-response calls

To call a Restate handler, use the generated clients and wait for its result: 
// To call a Service:
String svcResponse = MyServiceClient.fromContext(ctx).myHandler(request).await();

// To call a Virtual Object:
String objResponse = MyObjectClient.fromContext(ctx, objectKey).myHandler(request).await();

// To call a Workflow:
// `run` handler — can only be called once per workflow ID
String wfResponse = MyWorkflowClient.fromContext(ctx, workflowId).run(request).await();
// Other handlers can be called anytime within workflow retention
String status =
    MyWorkflowClient.fromContext(ctx, workflowId).interactWithWorkflow(request).await();
Use the generic clients when you don’t have access to typed clients or need dynamic service names: 
Target target = Target.service("MyService", "myHandler"); // or virtualObject or workflow
String response =
    ctx.call(Request.of(target, TypeTag.of(String.class), TypeTag.of(String.class), request))
        .await();
After a workflow’s run handler completes, other handlers can still be called for up to 24 hours (default). Update this via the service configuration.
Request-response calls between exclusive handlers of Virtual Objects may lead to deadlocks:
  • Cross deadlock: A → B and B → A (same keys).
  • Cycle deadlock: A → B → C → A.
Use the UI or CLI to cancel and unblock deadlocked invocations.

​
Sending messages

To send a message to another Restate handler without waiting for a response: 
MyServiceClient.fromContext(ctx).send().myHandler(request);
Restate handles message delivery and retries, so the handler can complete and return without waiting for the message to be processed. Use generic clients when you don’t have the service definition: 
Target target = Target.service("MyService", "myHandler"); // or virtualObject or workflow
ctx.send(Request.of(target, TypeTag.of(String.class), TypeTag.of(String.class), request));
Calls to a Virtual Object execute in order of arrival, serially. Example:
MyObjectClient.fromContext(ctx, objectKey).send().myHandler("I'm call A");
MyObjectClient.fromContext(ctx, objectKey).send().myHandler("I'm call B");
Call A is guaranteed to execute before B. However, other invocations may interleave between A and B.

​
Delayed messages

To send a message after a delay, use the generated clients with .send() and the Duration as second parameter: 
MyServiceClient.fromContext(ctx).send().myHandler(request, Duration.ofDays(5));
Or with the generic clients: 
Target target = Target.service("MyService", "myHandler"); // or virtualObject or workflow
ctx.send(
    Request.of(target, TypeTag.of(String.class), TypeTag.of(String.class), request),
    Duration.ofDays(5));
Learn how this is different from sleeping and then sending a message.

​
Using an idempotency key

To prevent duplicate executions of the same call, add an idempotency key: 
// For a request-response call
MyServiceClient.fromContext(ctx).myHandler(request, req -> req.idempotencyKey("abc123"));
// For a message
MyServiceClient.fromContext(ctx).send().myHandler(request, req -> req.idempotencyKey("abc123"));
Restate automatically deduplicates calls made during the same handler execution, so there’s no need to provide an idempotency key in that case. However, if multiple handlers might call the same service independently, you can use an idempotency key to ensure deduplication across those calls.

​
Attach to an invocation

To wait for or get the result of a previously sent message: 
var handle =
    MyServiceClient.fromContext(ctx)
        .send()
        .myHandler(request, req -> req.idempotencyKey("abc123"));
var response = handle.attach().await();
  • With an idempotency key: Wait for completion and retrieve the result.
  • Without an idempotency key: Can only wait, not retrieve the result.

​
Cancel an invocation

To cancel a running handler: 
var handle = MyServiceClient.fromContext(ctx).send().myHandler(request);
handle.cancel();

​
See also

  • SDK Clients: Call Restate services from external applications
  • Error Handling: Handle failures and terminal errors in service calls
  • Durable Timers: Implement timeouts for your service calls
  • Serialization: Customize how data is serialized between services
  • Sagas: Roll back or compensate for canceled service calls.
⌘I