An invocation is a request to execute a handler. The Restate SDK client library lets you invoke Restate handlers from anywhere in your application. Use this only in non-Restate services without access to the Restate Context.
Each invocation has its own unique ID and lifecycle. Have a look at managing invocations to learn how to manage the lifecycle of an invocation.
Always invoke handlers via the context, if you have access to it. Restate then attaches information about the invocation to the parent invocation.

​
Invoking handlers with the SDK clients

First, add the dependency to your project
  • For Java:
  • For Kotlin:
Then, register the service you want to invoke. Finally, connect to Restate and invoke the handler with your preferred semantics.
  • Request-response invocations allow you to wait on a response from the handler.
Client restateClient = Client.connect("http://localhost:8080");

// To call a service
String svcResponse = MyServiceClient.fromClient(restateClient).myHandler("Hi");

// To call a virtual object
String objResponse = MyObjectClient.fromClient(restateClient, "Mary").myHandler("Hi");

// To submit a workflow
String wfResponse =
    MyWorkflowClient.fromClient(restateClient, "Mary").submit("Hi").attach().response();
// To interact with a workflow
String status =
    MyWorkflowClient.fromClient(restateClient, "Mary").interactWithWorkflow("my signal");
  • One-way invocations allow you to send a message without waiting for a response.
Client restateClient = Client.connect("http://localhost:8080");

// To message a service
MyServiceClient.fromClient(restateClient).send().myHandler("Hi");

// To message a virtual object
MyObjectClient.fromClient(restateClient, "Mary").send().myHandler("Hi");

// To submit a workflow without waiting for the result
MyWorkflowClient.fromClient(restateClient, "Mary").submit("Hi");
  • Delayed invocations allow you to schedule an invocation for a later point in time.
Client restateClient = Client.connect("http://localhost:8080");

// To message a service with a delay
MyServiceClient.fromClient(restateClient).send().myHandler("Hi", Duration.ofDays(5));

// To message a virtual object with a delay
MyObjectClient.fromClient(restateClient, "Mary").send().myHandler("Hi", Duration.ofDays(5));

// To submit a workflow with a delay
MyWorkflowClient.fromClient(restateClient, "Mary").submit("Hi", Duration.ofDays(5));

​
Invoke a handler idempotently

By using Restate and an idempotency key, you can make any service call idempotent, without any extra code or setup. This is a very powerful feature to ensure that your system stays consistent and doesn’t perform the same operation multiple times. To make a service call idempotent, you can use the idempotency key feature. Add the idempotency key to the header via: 
Client restateClient = Client.connect("http://localhost:8080");
MyObjectClient.fromClient(restateClient, "Mary")
    .send()
    .myHandler("Hi", opt -> opt.idempotencyKey("abc"));
After the invocation completes, Restate persists the response for a retention period of one day (24 hours). If you re-invoke the service with the same idempotency key within 24 hours, Restate sends back the same response and doesn’t re-execute the request to the service. The call options, with which we set the idempotency key, also let you add other headers to the request.
Check out the service configuration docs to tune the retention time.

​
Retrieve result of invocations and workflows

You can use the client library to retrieve the results of invocations with an idempotency key or workflows.

​
Attach to an invocation with an idempotency key

For invocations with an idempotency key, you can attach to the invocation and wait for it to finish: 
Client restateClient = Client.connect("http://localhost:8080");

// The call to which we want to attach later
var handle =
    MyServiceClient.fromClient(restateClient)
        .send()
        .myHandler("Hi", opt -> opt.idempotencyKey("my-idempotency-key"));

// ... do something else ...

// ---------------------------------
// OPTION 1: With the handle returned by the call
// - Attach
String result1 = handle.attach().response();
// - Peek
Output<String> output = handle.getOutput().response();
if (output.isReady()) {
  String result2 = output.getValue();
}

// ---------------------------------
// OPTION 2: With the Invocation ID
// Retrieve the invocation ID from the handle and send it to another process
String invocationId = handle.invocationId();

// Attach/peek later from the other process
var handle2 = restateClient.invocationHandle(invocationId, String.class);
// use it to attach or peek (see above)

// ---------------------------------
// OPTION 3: With the idempotency key
var myService = Target.service("MyService", "myHandler");
var handle3 =
    restateClient.idempotentInvocationHandle(myService, "my-idempotency-key", String.class);
// use it to attach or peek (see above)

​
Attach/peek at a workflow execution

For workflows, you can attach to the workflow execution and wait for it to finish or peek at the output: 
Client restateClient = Client.connect("http://localhost:8080");

// The workflow to which we want to attach later
var wfHandle = MyWorkflowClient.fromClient(restateClient, "Mary").submit("Hi");

// ... do something else ...

// ---------------------------------
// OPTION 1: With the handle returned by the workflow submission
// - Attach
String result = wfHandle.attach().response();
// - Peek
Output<String> output = wfHandle.getOutput().response();
if (output.isReady()) {
  String result2 = output.getValue();
}

// ---------------------------------
// OPTION 2: With the workflow ID
var wfHandle2 = restateClient.workflowHandle("MyWorkflow", "wf-id", String.class);
// use it to attach or peek (see above)