Workflow API reference

Workflow API reference

Detailed documentation on the workflow API

Component format

A Dapr workflow.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: workflow.<TYPE>
  version: v1.0-alpha1
  metadata:
  - name: <NAME>
    value: <VALUE>

Setting	Description
`metadata.name`	The name of the workflow component.
`spec/metadata`	Additional metadata parameters specified by workflow component

Supported workflow methods

POST start workflow request

POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/<instanceId>/start

POST terminate workflow request

POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>/terminate

GET workflow request

GET http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/<instanceId>

URL parameters

Parameter	Description
`workflowComponentName`	Current default is `dapr` for Dapr Workflows
`workflowName`	Identify the workflow type
`instanceId`	Unique value created for each run of a specific workflow

Headers

As part of the start HTTP request, the caller can optionally include one or more dapr-workflow-metadata HTTP request headers. The format of the header value is a list of {key}={value} values, similar to the format for HTTP cookie request headers. These key/value pairs are saved in the workflow instance’s metadata and can be made available for search (in cases where the workflow implementation supports this kind of search).

HTTP responses

Response codes

Code	Description
`202`	Accepted
`400`	Request was malformed
`500`	Request formatted correctly, error in dapr code or underlying component

Examples of response body for each method

POST start workflow response body

  "WFInfo": {
    "instance_id": "SampleWorkflow"
  }

POST terminate workflow response body

HTTP/1.1 202 Accepted
Server: fasthttp
Date: Thu, 12 Jan 2023 21:31:16 GMT
Content-Type: application/json
Content-Length: 139
Traceparent: 00-e3dedffedbeb9efbde9fbed3f8e2d8-5f38960d43d24e98-01
Connection: close

GET workflow response body

HTTP/1.1 202 Accepted
Server: fasthttp
Date: Thu, 12 Jan 2023 21:31:16 GMT
Content-Type: application/json
Content-Length: 139
Traceparent: 00-e3dedffedbeb9efbde9fbed3f8e2d8-5f38960d43d24e98-01
Connection: close 
{
  "WFInfo": {
    "instance_id": "SampleWorkflow"
  },
  "start_time": "2023-01-12T21:31:13Z",
  "metadata": {
    "status": "Running",
    "task_queue": "WorkflowSampleQueue"
  }
 }

Next Steps

Last modified February 16, 2023: remove left over todo links (67e809ab)