Skip to main content

Admin API

API docs by Redocly

Admin API (1.1.3)

service_handler

List service handlers

List all the handlers of the given service.

path Parameters
service
required
string

Fully qualified service name.

Responses

Response samples

Content type
application/json
{
  • "handlers": [
    ]
}

Get service handler

Get the handler of a service

path Parameters
service
required
string

Fully qualified service name.

handler
required
string

Handler name.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "ty": "Exclusive",
  • "input_description": "string",
  • "output_description": "string"
}

version

Admin version information

Obtain admin version information.

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "min_admin_api_version": 0,
  • "max_admin_api_version": 0
}

service

Modify a service state

Modify service state

path Parameters
service
required
string

Fully qualified service name.

Request Body schema: application/json
required
version
string or null (Version)

If set, the latest version of the state is compared with this value and the operation will fail when the versions differ.

object_key
required
string (Service key)

To what virtual object key to apply this change

required
object (New State)

The new state to replace the previous state with

Responses

Request samples

Content type
application/json
{
  • "version": "string",
  • "object_key": "string",
  • "new_state": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "restate_code": "string"
}

List services

List all registered services.

Responses

Response samples

Content type
application/json
{
  • "services": [
    ]
}

Get service

Get a registered service.

path Parameters
service
required
string

Fully qualified service name.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "handlers": [
    ],
  • "ty": "Service",
  • "deployment_id": "string",
  • "revision": 0,
  • "public": true,
  • "idempotency_retention": "string",
  • "workflow_completion_retention": "string"
}

Modify a service

Modify a registered service.

path Parameters
service
required
string

Fully qualified service name.

Request Body schema: application/json
required
public
boolean or null (Public)

If true, the service can be invoked through the ingress. If false, the service can be invoked only from another Restate service.

idempotency_retention
string or null (Idempotency retention)

Modify the retention of idempotent requests for this service.

Can be configured using the humantime format or the ISO8601.

workflow_completion_retention
string or null (Workflow completion retention)

Modify the retention of the workflow completion. This can be modified only for workflow services!

Can be configured using the humantime format or the ISO8601.

Responses

Request samples

Content type
application/json
{
  • "public": true,
  • "idempotency_retention": "string",
  • "workflow_completion_retention": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "handlers": [
    ],
  • "ty": "Service",
  • "deployment_id": "string",
  • "revision": 0,
  • "public": true,
  • "idempotency_retention": "string",
  • "workflow_completion_retention": "string"
}

deployment

Get deployment

Get deployment metadata

path Parameters
deployment
required
string

Deployment identifier

Responses

Response samples

Content type
application/json
{
  • "arn": "string",
  • "assume_role_arn": "string",
  • "additional_headers": {
    },
  • "created_at": "string",
  • "min_protocol_version": 0,
  • "max_protocol_version": 0,
  • "id": "string",
  • "services": [
    ]
}

Delete deployment

Delete deployment. Currently it's supported to remove a deployment only using the force flag

path Parameters
deployment
required
string

Deployment identifier

query Parameters
force
boolean

If true, the deployment will be forcefully deleted. This might break in-flight invocations, use with caution.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "restate_code": "string"
}

List deployments

List all registered deployments.

Responses

Response samples

Content type
application/json
{
  • "deployments": [
    ]
}

Create deployment

Create deployment. Restate will invoke the endpoint to gather additional information required for registration, such as the services exposed by the deployment. If the deployment is already registered, this method will fail unless force is set to true.

Request Body schema: application/json
required
Any of
uri
required
string (Uri)

Uri to use to discover/invoke the http deployment.

object or null (Additional headers)

Additional headers added to the discover/invoke requests to the deployment.

use_http_11
boolean (Use http1.1)
Default: false

If true, discovery will be attempted using a client that defaults to HTTP1.1 instead of a prior-knowledge HTTP2 client. HTTP2 may still be used for TLS servers that advertise HTTP2 support via ALPN. HTTP1.1 deployments will only work in request-response mode.

force
boolean (Force)
Default: true

If true, it will override, if existing, any deployment using the same uri. Beware that this can lead in-flight invocations to an unrecoverable error state.

By default, this is true but it might change in future to false.

See the versioning documentation for more information.

dry_run
boolean (Dry-run mode)
Default: false

If true, discovery will run but the deployment will not be registered. This is useful to see the impact of a new deployment before registering it.

Responses

Request samples

Content type
application/json
{
  • "arn": "string",
  • "assume_role_arn": "string",
  • "additional_headers": {
    },
  • "force": true,
  • "dry_run": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "services": [
    ]
}

subscription

List subscriptions

List all subscriptions.

query Parameters
sink
string

Filter by the exact specified sink.

source
string

Filter by the exact specified source.

Responses

Response samples

Content type
application/json
{
  • "subscriptions": [
    ]
}

Create subscription

Create subscription.

Request Body schema: application/json
required
source
required
string (Source)

Source uri. Accepted forms:

  • kafka://<cluster_name>/<topic_name>, e.g. kafka://my-cluster/my-topic
sink
required
string (Sink)

Sink uri. Accepted forms:

  • service://<service_name>/<service_name>, e.g. service://Counter/count
object or null (Options)

Additional options to apply to the subscription.

Responses

Request samples

Content type
application/json
{
  • "source": "string",
  • "sink": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "source": "string",
  • "sink": "string",
  • "options": {
    }
}

Get subscription

Get subscription

path Parameters
subscription
required
string

Subscription identifier

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "source": "string",
  • "sink": "string",
  • "options": {
    }
}

Delete subscription

Delete subscription.

path Parameters
subscription
required
string

Subscription identifier

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "restate_code": "string"
}

health

Health check

Check REST API Health.

Responses

invocation

Delete an invocation

Delete the given invocation. By default, an invocation is terminated by gracefully cancelling it. This ensures virtual object state consistency. Alternatively, an invocation can be killed which does not guarantee consistency for virtual object instance state, in-flight invocations to other services, etc. A stored completed invocation can also be purged

path Parameters
invocation_id
required
string

Invocation identifier.

query Parameters
mode
string (DeletionMode)
Enum: "Cancel" "Kill" "Purge"

If cancel, it will gracefully terminate the invocation. If kill, it will terminate the invocation with a hard stop. If purge, it will only cleanup the response for completed invocations, and leave unaffected an in-flight invocation.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "restate_code": "string"
}

openapi

OpenAPI specification

https://swagger.io/specification/

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}