Skip to main content

Documentation Index

Fetch the complete documentation index at: https://restate-6d46e1dc-mintlify-java-sdk-v2-7-0-1778569850.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

An invocation is a request to execute a handler. You can invoke handlers over HTTP with or without waiting for a response, and with or without an idempotency key. Make sure to first register the handler you want to invoke. The UI helps you with invoking your services. Open the UI at port 9070, register your service, click on the service, open the playground, and invoke your handlers from there.
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.

​
Request-response calls

You can invoke services over HTTP 1.1 or higher. Request/response bodies should be encoded as JSON. Invoking myHandler of myService as follows: 
curl localhost:8080/MyService/myHandler \
  --json '{"name": "Mary", "age": 25}'
Invoke myHandler of myVirtualObject for myObjectKey as follows: 
curl localhost:8080/MyVirtualObject/myObjectKey/myHandler \
  --json '{"name": "Mary", "age": 25}'
Call the run handler of the MyWorkflow as follows: 
curl localhost:8080/MyWorkflow/myWorkflowId/run \
  --json '{"name": "Mary", "age": 25}'
A workflow can be submitted only once. Resubmission of the same workflow will fail with “Previously accepted”. The invocation ID can be found in the request header x-restate-id. Follow the same pattern for calling the other handlers of the workflow.
Note that all invocations go first via the Restate Server. The server then forwards the request to the appropriate service. Therefore, localhost:8080 refers to ingress port of the Restate Server, not the service instance.

​
Sending messages

If you do not want to wait for the response, you can also send a message by adding /send to the URL path: 
curl localhost:8080/MyService/myHandler/send \
  --json '{"name": "Mary", "age": 25}'
Example output: 
{"invocationId":"inv_1aiqX0vFEFNH1Umgre58JiCLgHfTtztYK5","status":"Accepted"}
The response contains the Invocation ID. You can use this identifier to cancel or kill the invocation.

​
Delayed messages

You can delay the message by adding a delay request parameter in ISO8601 notation or using humantime format: 
curl "localhost:8080/MyService/myHandler/send?delay=10s" \
    --json '{"name": "Mary", "age": 25}'
You cannot yet use this feature for workflows. Workflows can only be scheduled with a delay from within another Restate handler (TS/Java/Kotlin).

​
Using an idempotency key

You can send requests to Restate providing an idempotency key, through the Idempotency-Key header: 
curl localhost:8080/MyService/myHandler \
  -H 'idempotency-key: ad5472esg4dsg525dssdfa5loi' \
  --json '{"name": "Mary", "age": 25}'
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. Check out the service configuration docs to tune the retention time.
With 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.

​
Cancel

You can cancel an invocation as follows:
curl
curl -X PATCH http://localhost:9070/invocations/inv_1gdJBtdVEcM942bjcDmb1c1khoaJe11Hbz/cancel
Read the detailed docs on cancelling invocations

​
Attach to an invocation

Restate allows you to retrieve the result of workflows and invocations with an idempotency key. There are two options:
  • To attach to an invocation or workflow and wait for it to finish, use /attach.
  • To peek at the output of an invocation or workflow, use /output. This will return:
    • {"message":"not ready"} for ongoing workflows
    • The result for finished workflows
    • {"message":"not found"} for non-existing workflows
You can attach to a service/object invocation only if the invocation used an idempotency key: 
# Via invocation ID
curl localhost:8080/restate/invocation/myInvocationId/attach
curl localhost:8080/restate/invocation/myInvocationId/output

# For Services, via idempotency key
curl localhost:8080/restate/invocation/MyService/myHandler/myIdempotencyKey/attach
curl localhost:8080/restate/invocation/MyService/myHandler/myIdempotencyKey/output

# For Virtual Objects, via idempotency key
curl localhost:8080/restate/invocation/myObject/myKey/myHandler/myIdempotencyKey/attach
curl localhost:8080/restate/invocation/myObject/myKey/myHandler/myIdempotencyKey/output

# For Workflows, with the Workflow ID
curl localhost:8080/restate/workflow/MyWorkflow/myWorkflowId/attach
curl localhost:8080/restate/workflow/MyWorkflow/myWorkflowId/output

​
OpenAPI support

Restate exposes for every service an OpenAPI 3.1 definition, to get it: 
curl localhost:9070/services/MyService/openapi > MyService_openapi.json
You can use this definition with any OpenAPI 3.1 compliant tool to generate clients for your service, such as openapi-generator. Depending on the SDKs, the rich input/output JSON schemas are included as well. At the moment, rich schemas are supported for: