HTTP
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.
Request-response calls over HTTP
You can invoke services over HTTP 1.1 or higher. Request/response bodies should be encoded as JSON.
To invoke Services, construct the path as follows:
curl localhost:8080/MyService/myHandler \ -H 'content-type: application/json' \ -d '{"name": "Mary", "age": 25}'
To invoke Virtual Objects, construct the path as follows:
curl localhost:8080/MyVirtualObject/myObjectKey/myHandler \ -H 'content-type: application/json' \ -d '{"name": "Mary", "age": 25}'
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"}
The response contains the Invocation identifier. You can use this identifier to cancel or kill the invocation.
Use this to invoke long-running workflows.
Sending a delayed message over HTTP
You can delay the message by adding a delay request parameter in ISO8601 notation or in seconds:
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.
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.
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.