dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: Provide more structured API docs for Workflow API 

Signed-off-by: Tom Kerkhove <kerkhove.tom@gmail.com>
This commit is contained in:
Tom Kerkhove 2023-03-14 10:33:04 +00:00
parent d0c107eb8a
commit 7bdefeb5eb
1 changed files with 105 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

161
daprdocs/content/en/reference/api/workflow_api.md
View File

@ -5,39 +5,95 @@ linkTitle: "Workflow API"
description: "Detailed documentation on the workflow API"
weight: 900
---
## Component format
A Dapr `workflow.yaml` component file has the following structure:
```yaml
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 |
Dapr provides users with the ability to interact with workflows and comes with a built-in `dapr` component.
## Start workflow request
Start a workflow instance with the given name and instance id.
## Supported workflow methods
### POST start workflow request
```bash
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/<instanceId>/start
```
### POST terminate workflow request
### 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
### Request Contents
In the request you can pass along headers:
```json
{
"input": // argument(s) to pass to the workflow which can be any valid JSON data type (such as objects, strings, numbers, arrays, etc.)
}
```
### HTTP Response codes
Code | Description
---- | -----------
`202` | Accepted
`400` | Request was malformed
`500` | Request formatted correctly, error in dapr code or underlying component
### Response Contents
The API call will provide a response similar to this:
```json
{
  "WFInfo": {
    "instance_id": "SampleWorkflow"
  }
}
```
## Terminate workflow request
Terminate a running workflow instance with the given name and instance id.
```bash
POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>/terminate
```
### GET workflow request
### 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
### HTTP Response codes
Code | Description
---- | -----------
`202` | Accepted
`400` | Request was malformed
`500` | Request formatted correctly, error in dapr code or underlying component
### Response Contents
The API call will provide a response similar to this:
```bash
HTTP/1.1 202 Accepted
Server: fasthttp
Date: Thu, 12 Jan 2023 21:31:16 GMT
Traceparent: 00-e3dedffedbeb9efbde9fbed3f8e2d8-5f38960d43d24e98-01
Connection: close 
```
### Get workflow request
Get information about a given workflow instance.
```bash
GET http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/<instanceId>
```
@ -50,15 +106,7 @@ Parameter | Description
`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
### HTTP Response codes
Code | Description
---- | -----------
@ -66,31 +114,9 @@ Code | Description
`400` | Request was malformed
`500` | Request formatted correctly, error in dapr code or underlying component
### Examples of response body for each method
### Response Contents
#### POST start workflow response body
```bash
  "WFInfo": {
    "instance_id": "SampleWorkflow"
  }
```
#### POST terminate workflow response body
```bash
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
The API call will provide a response similar to this:
```bash
HTTP/1.1 202 Accepted
@ -113,6 +139,29 @@ Connection: close 
}
```
## Component format
A Dapr `workflow.yaml` component file has the following structure:
```yaml
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 |
However, Dapr comes with a built-in `dapr` workflow component that is built on Dapr Actors. No component file is required to use the built-in Dapr workflow component.
## Next Steps