From 0ef572f3eb391ac35b7fd790eb7d68c00c420512 Mon Sep 17 00:00:00 2001
From: Chris Gillum <cgillum@microsoft.com>
Date: Mon, 1 May 2023 18:21:21 -0700
Subject: [PATCH] Changes to v1.10 HTTP APIs for v1.11

Signed-off-by: Chris Gillum <cgillum@microsoft.com>
---
 .../workflow/howto-manage-workflow.md         |  6 +-
 .../content/en/reference/api/workflow_api.md  | 66 ++++++-------------
 2 files changed, 25 insertions(+), 47 deletions(-)

diff --git a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md
index b876c5d9f..34aa10603 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md
@@ -45,9 +45,11 @@ Manage your workflow using HTTP calls. The example below plugs in the properties
 To start your workflow with an ID `12345678`, run:
 
 ```bash
-POST http://localhost:3500/v1.0-alpha1/workflows/dapr/OrderProcessingWorkflow/12345678/start
+POST http://localhost:3500/v1.0-alpha1/workflows/dapr/OrderProcessingWorkflow/start?instanceID=12345678
 ```
 
+Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
+
 ### Terminate workflow
 
 To terminate your workflow with an ID `12345678`, run:
@@ -61,7 +63,7 @@ POST http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678/terminate
 To fetch workflow information (outputs and inputs) with an ID `12345678`, run:
 
 ```bash
-GET http://localhost:3500/v1.0-alpha1/workflows/dapr/OrderProcessingWorkflow/12345678
+GET http://localhost:3500/v1.0-alpha1/workflows/dapr/12345678
 ```
 
 Learn more about these HTTP calls in the [workflow API reference guide]({{< ref workflow_api.md >}}).
diff --git a/daprdocs/content/en/reference/api/workflow_api.md b/daprdocs/content/en/reference/api/workflow_api.md
index ebf7ad2c7..442b206ad 100644
--- a/daprdocs/content/en/reference/api/workflow_api.md
+++ b/daprdocs/content/en/reference/api/workflow_api.md
@@ -10,29 +10,25 @@ Dapr provides users with the ability to interact with workflows and comes with a
 
 ## Start workflow request
 
-Start a workflow instance with the given name and instance ID.
+Start a workflow instance with the given name and optionally, an instance ID.
 
 ```bash
-POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/<instanceId>/start
+POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/start[?instanceId=<instanceId>]
 ```
 
+Note that workflow instance IDs can only contain alphanumeric characters, underscores, and dashes.
+
 ### 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
+`instanceId` | (Optional) Unique value created for each run of a specific workflow
 
 ### Request content
 
-In the request you can pass along relevant input information that will be passed to the workflow:
-
-```json
-{
-  "input": // argument(s) to pass to the workflow which can be any valid JSON data type (such as objects, strings, numbers, arrays, etc.)
-}
-```
+Any request content will be passed to the workflow as input. The Dapr API passes the content as-is without attempting to interpret it.
 
 ### HTTP response codes
 
@@ -48,9 +44,7 @@ The API call will provide a response similar to this:
 
 ```json
 {
-  "WFInfo": {
-    "instance_id": "SampleWorkflow"
-  }
+    "instanceID": "12345678"
 }
 ```
 
@@ -59,7 +53,7 @@ The API call will provide a response similar to this:
 Terminate a running workflow instance with the given name and instance ID.
 
 ```bash
-POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>/terminate
+POST http://localhost:3500/v1.0-alpha1/workflows/<instanceId>/terminate
 ```
 
 ### URL parameters
@@ -67,7 +61,6 @@ POST http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instan
 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
@@ -80,22 +73,14 @@ Code | Description
 
 ### Response content
 
-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 
-```
+This API does not return any content.
 
 ### Get workflow request
 
 Get information about a given workflow instance.
 
 ```bash
-GET http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflowName>/<instanceId>
+GET http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<instanceId>
 ```
 
 ### URL parameters
@@ -103,39 +88,30 @@ GET http://localhost:3500/v1.0-alpha1/workflows/<workflowComponentName>/<workflo
 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
+`200`  | OK
 `400`  | Request was malformed
 `500`  | Request formatted correctly, error in dapr code or underlying component
 
 ### Response content
 
-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
-Content-Type: application/json
-Content-Length: 139
-Traceparent: 00-e3dedffedbeb9efbde9fbed3f8e2d8-5f38960d43d24e98-01
-Connection: close 
+The API call will provide a JSON response similar to this:
 
+```json
 {
-  "WFInfo": {
-    "instance_id": "SampleWorkflow"
-  },
-  "start_time": "2023-01-12T21:31:13Z",
-  "metadata": {
-    "status": "Running",
-    "task_queue": "WorkflowSampleQueue"
-  }
+  "createdAt": "2023-01-12T21:31:13Z",
+  "instanceID": "12345678",
+  "lastUpdatedAt": "2023-01-12T21:31:13Z",
+  "properties": {
+    "property1": "value1",
+    "property2": "value2",
+  },
+  "runtimeStatus": "RUNNING",
  }
 ```