Skip to main content

HTTP

You can invoke handlers over HTTP with or without waiting for a response, and with or without an idempotency key.

info

Make sure to first register the handler you want to invoke.

Request-response calls over HTTP​

You can invoke services over HTTP 1.1 or higher. Request/response bodies should be encoded as JSON.

Invoking Services​

Invoke myHandler of myService as follows:


curl localhost:8080/MyService/myHandler \
-H 'content-type: application/json' \
-d '{"name": "Mary", "age": 25}'

Invoking Services​

Invoke myHandler of myService as follows:


curl localhost:8080/MyService/myHandler \
-H 'content-type: application/json' \
-d '{"name": "Mary", "age": 25}'

Invoking Virtual Objects​

Invoke myHandler of myVirtualObject for myKey as follows:


curl localhost:8080/MyVirtualObject/myObjectKey/myHandler \
-H 'content-type: application/json' \
-d '{"name": "Mary", "age": 25}'

Invoking Virtual Objects​

Invoke myHandler of myVirtualObject for myKey as follows:


curl localhost:8080/MyVirtualObject/myObjectKey/myHandler \
-H 'content-type: application/json' \
-d '{"name": "Mary", "age": 25}'

Invoke Workflows​

Call the run handler of the MyWorkflow as follows:


curl localhost:8080/MyWorkflow/myWorkflowId/run \
-H 'content-type: application/json' \
-d '{"name": "Mary", "age": 25}'

Invoke Workflows​

Call the run handler of the MyWorkflow as follows:


curl localhost:8080/MyWorkflow/myWorkflowId/run \
-H 'content-type: application/json' \
-d '{"name": "Mary", "age": 25}'

Follow the same pattern for calling the other handlers of the workflow.

Restate as proxy

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 a message over HTTP​

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 \
-H 'content-type: application/json' \
-d '{"name": "Mary", "age": 25}'

Output

{"invocationId":"inv_1aiqX0vFEFNH1Umgre58JiCLgHfTtztYK5","status":"Accepted"}

The response contains the Invocation ID. You can use this identifier to cancel or kill the invocation.

Sending a delayed message over HTTP​

You can delay the message by adding a delay request parameter in ISO8601 notation or using humantime format:

humantime
ISO8601

curl localhost:8080/MyService/myHandler/send?delay=10s \
-H 'content-type: application/json' \
-d '{"name": "Mary", "age": 25}'

Not supported for workflows

You cannot yet use this feature for workflows. Workflows can only be scheduled with a delay from within another Restate handler (TS/Java/Kotlin).

Invoke a handler idempotently​

You can send requests to Restate providing an idempotency key, through the Idempotency-Key header:


curl localhost:8080/MyService/myHandler \
-H 'idempotency-key: ad5472esg4dsg525dssdfa5loi' \
-H 'content-type: application/json' \
-d '{"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.

Make any service call idempotent with Restate

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.

Tuning retention time

You can tune the retention time on a service-level by using the Admin API (docs):


curl -X PATCH localhost:9070/services/MyService \
-H 'content-type: application/json' \
-d '{"idempotency_retention": "2days"}'

The retention time is in humantime format.

Retrieve result of invocations and workflows​

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