Restate Service Operations

naftiko: "1.0.0-alpha1"

info:
  label: "Restate Service Operations"
  description: "Unified capability for managing the full lifecycle of Restate services and deployments. Covers registering service deployments, inspecting service metadata and handlers, managing in-flight invocations, and configuring Kafka subscriptions for event-driven execution."
  tags:
    - Durable Execution
    - Deployments
    - Services
    - Invocations
    - Kafka
    - Operations
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      RESTATE_ADMIN_URL: RESTATE_ADMIN_URL

capability:
  consumes:
    - import: restate-admin
      location: ./shared/restate-admin.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: restate-operations-api
      description: "Unified REST API for Restate service operations, invocation management, and Kafka subscriptions."
      resources:
        - path: /v1/deployments
          name: deployments
          description: "Register and manage service deployments"
          operations:
            - method: GET
              name: list-deployments
              description: "List all registered service deployments"
              call: "restate-admin.list-deployments"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-deployment
              description: "Register a new service deployment"
              call: "restate-admin.create-deployment"
              with:
                uri: "rest.body.uri"
                force: "rest.body.force"
                dry_run: "rest.body.dry_run"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/deployments/{deployment}
          name: deployment
          description: "Individual deployment management"
          operations:
            - method: GET
              name: get-deployment
              description: "Get deployment details"
              call: "restate-admin.get-deployment"
              with:
                deployment: "rest.deployment"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-deployment
              description: "Delete a deployment"
              call: "restate-admin.delete-deployment"
              with:
                deployment: "rest.deployment"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/services
          name: services
          description: "Service registry and metadata"
          operations:
            - method: GET
              name: list-services
              description: "List all registered services"
              call: "restate-admin.list-services"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/services/{service}
          name: service
          description: "Individual service management"
          operations:
            - method: GET
              name: get-service
              description: "Get service metadata and handlers"
              call: "restate-admin.get-service"
              with:
                service: "rest.service"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PATCH
              name: modify-service
              description: "Modify service configuration"
              call: "restate-admin.modify-service"
              with:
                service: "rest.service"
                public: "rest.body.public"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/services/{service}/handlers
          name: service-handlers
          description: "Service handler inspection"
          operations:
            - method: GET
              name: list-service-handlers
              description: "List all handlers for a service"
              call: "restate-admin.list-service-handlers"
              with:
                service: "rest.service"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/invocations/{invocation_id}/cancel
          name: invocation-cancel
          description: "Cancel active invocations"
          operations:
            - method: PATCH
              name: cancel-invocation
              description: "Cancel an in-flight invocation"
              call: "restate-admin.cancel-invocation"
              with:
                invocation_id: "rest.invocation_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/invocations/{invocation_id}/kill
          name: invocation-kill
          description: "Force kill invocations"
          operations:
            - method: PATCH
              name: kill-invocation
              description: "Forcefully kill an invocation"
              call: "restate-admin.kill-invocation"
              with:
                invocation_id: "rest.invocation_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/invocations/{invocation_id}/purge
          name: invocation-purge
          description: "Purge completed invocations"
          operations:
            - method: PATCH
              name: purge-invocation
              description: "Purge a completed invocation"
              call: "restate-admin.purge-invocation"
              with:
                invocation_id: "rest.invocation_id"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/subscriptions
          name: subscriptions
          description: "Kafka subscriptions for event-driven invocations"
          operations:
            - method: GET
              name: list-subscriptions
              description: "List all Kafka subscriptions"
              call: "restate-admin.list-subscriptions"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-subscription
              description: "Create a Kafka subscription"
              call: "restate-admin.create-subscription"
              with:
                source: "rest.body.source"
                sink: "rest.body.sink"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/cluster-health
          name: cluster-health
          description: "Cluster health and version"
          operations:
            - method: GET
              name: cluster-health
              description: "Get cluster health status"
              call: "restate-admin.cluster-health"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: restate-operations-mcp
      transport: http
      description: "MCP server for AI-assisted Restate service operations, deployment management, and invocation control."
      tools:
        - name: list-deployments
          description: "List all Restate service deployments registered with the cluster"
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "restate-admin.list-deployments"
          outputParameters:
            - type: object
              mapping: "$."
        - name: register-deployment
          description: "Register a new service endpoint with Restate so it can receive invocations"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "restate-admin.create-deployment"
          with:
            uri: "tools.uri"
            force: "tools.force"
            dry_run: "tools.dry_run"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-deployment
          description: "Get details and services of a specific Restate deployment"
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "restate-admin.get-deployment"
          with:
            deployment: "tools.deployment"
          outputParameters:
            - type: object
              mapping: "$."
        - name: delete-deployment
          description: "Remove a service deployment from Restate"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "restate-admin.delete-deployment"
          with:
            deployment: "tools.deployment"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-services
          description: "List all services registered in Restate"
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "restate-admin.list-services"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-service
          description: "Get metadata and handler list for a specific Restate service"
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "restate-admin.get-service"
          with:
            service: "tools.service"
          outputParameters:
            - type: object
              mapping: "$."
        - name: modify-service
          description: "Update Restate service configuration such as public access"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "restate-admin.modify-service"
          with:
            service: "tools.service"
            public: "tools.public"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-service-handlers
          description: "List all durable handlers for a Restate service"
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "restate-admin.list-service-handlers"
          with:
            service: "tools.service"
          outputParameters:
            - type: object
              mapping: "$."
        - name: cancel-invocation
          description: "Cancel an in-flight Restate invocation by ID"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "restate-admin.cancel-invocation"
          with:
            invocation_id: "tools.invocation_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: kill-invocation
          description: "Force kill a Restate invocation (immediate termination)"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "restate-admin.kill-invocation"
          with:
            invocation_id: "tools.invocation_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: purge-invocation
          description: "Purge a completed Restate invocation and free its associated state"
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "restate-admin.purge-invocation"
          with:
            invocation_id: "tools.invocation_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-subscriptions
          description: "List all Kafka subscriptions configured in Restate"
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "restate-admin.list-subscriptions"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-subscription
          description: "Create a Kafka subscription to trigger Restate handlers on incoming messages"
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "restate-admin.create-subscription"
          with:
            source: "tools.source"
            sink: "tools.sink"
          outputParameters:
            - type: object
              mapping: "$."
        - name: cluster-health
          description: "Check the health status of the Restate cluster"
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "restate-admin.cluster-health"
          outputParameters:
            - type: object
              mapping: "$."