From 53418aa66ec575b23b2594b76a9cd551710d0bb6 Mon Sep 17 00:00:00 2001 From: "justin.weng" Date: Wed, 13 Sep 2023 14:41:49 +1000 Subject: [PATCH 1/3] Add HTTP API documentation --- src/docs/03-concepts/10-http-api.md | 2185 +++++++++++++++++++++++++++ 1 file changed, 2185 insertions(+) create mode 100644 src/docs/03-concepts/10-http-api.md diff --git a/src/docs/03-concepts/10-http-api.md b/src/docs/03-concepts/10-http-api.md new file mode 100644 index 000000000..76f3f6d57 --- /dev/null +++ b/src/docs/03-concepts/10-http-api.md @@ -0,0 +1,2185 @@ +--- +layout: default +title: HTTP API +permalink: /docs/concepts/http-api +--- + +# Using HTTP API + +## Introduction + +From **version 1.2.0** onwards, Cadence has introduced HTTP API support, which allows you to interact with the Cadence server +using the HTTP protocol. To put this into perspective, HTTP/JSON communication is a flexible method for server interaction. +In the context of Cadence, this implies that a range of RPC methods can be exposed and invoked using the HTTP protocol. +This enhancement broadens the scope of interaction with the Cadence server, enabling the use of any programming language that supports HTTP. +Consequently, you can leverage this functionality to initiate or terminate workflows from your bash scripts, monitor the +status of your cluster, or execute any other operation that the Cadence RPC declaration supports. + +## Setup + +### Updating Cadence configuration files + +To enable “start workflow” HTTP API, add `http` section to Cadence RPC configuration settings (e.g., in `base.yaml` or `development.yaml`): + +```yaml +services: + frontend: + rpc: + <...> + http: + port: 8800 + procedures: + - uber.cadence.api.v1.WorkflowAPI::StartWorkflowExecution +``` + +Then you can run Cadence server in the following ways to use HTTP API. + +### Using local binaries + +Build and run `./cadence-server` as described in [Developing Cadence](https://github.com/uber/cadence/blob/master/CONTRIBUTING.md). + +### Using “docker run” command + +Refer to instructions described +in [Using docker image for production](https://github.com/uber/cadence/tree/master/docker#using-docker-image-for-production). + +Additionally add two more environment variables: + +```bash +docker run +<...> + -e FRONTEND_HTTP_PORT=8800 -- HTTP PORT TO LISTEN + -e FRONTEND_HTTP_PROCEDURES=uber.cadence.api.v1.WorkflowAPI::StartWorkflowExecution -- List of API methods exposed + ubercadence/server: +``` + +### Using docker-compose + +Add HTTP environment variables to `docker/docker-compose.yml` configuration: + +```yaml +cadence: + image: ubercadence/server:master-auto-setup + ports: + - "8000:8000" + - "8001:8001" + - "8002:8002" + - "8003:8003" + - "7933:7933" + - "7934:7934" + - "7935:7935" + - "7939:7939" + - "7833:7833" + - "8800:8800" + environment: + - "CASSANDRA_SEEDS=cassandra" + - "PROMETHEUS_ENDPOINT_0=0.0.0.0:8000" + - "PROMETHEUS_ENDPOINT_1=0.0.0.0:8001" + - "PROMETHEUS_ENDPOINT_2=0.0.0.0:8002" + - "PROMETHEUS_ENDPOINT_3=0.0.0.0:8003" + - "DYNAMIC_CONFIG_FILE_PATH=config/dynamicconfig/development.yaml" + - "FRONTEND_HTTP_PORT=8800" + - "FRONTEND_HTTP_PROCEDURES=uber.cadence.api.v1.WorkflowAPI::StartWorkflowExecution" +``` + +## Using HTTP API + +Start a workflow using curl command + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: rpc-client-name' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::StartWorkflowExecution' \ + -d @data.json +``` + +Where `data.json` content looks something like this: + +```json +{ + "domain": "sample-domain", + "workflowId": "workflowid123", + "execution_start_to_close_timeout": "11s", + "task_start_to_close_timeout": "10s", + "workflowType": { + "name": "workflow_type" + }, + "taskList": { + "name": "tasklist-name" + }, + "identity": "My custom caller identity", + "requestId": "4D1E4058-6FCF-4BA8-BF16-8FA8B02F9651" +} +``` + +## HTTP API Reference + +### Admin API + +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.admin.v1.AdminAPI::AddSearchAttribute + +#### Add search attributes to whitelist + +##### Headers + +| name | example | +|----------------|----------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.admin.v1.AdminAPI::AddSearchAttribute | + +##### Example payload + +```json +{ + "search_attribute": { + "custom_key": 1 + } +} +``` + +Search attribute types + +| type | value | +|----------|-------| +| String | 1 | +| Keyword | 2 | +| Int | 3 | +| Double | 4 | +| DateTime | 5 | + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.admin.v1.AdminAPI::AddSearchAttribute' \ + -d \ + '{ + "search_attribute": { + "custom_key": 1 + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.admin.v1.AdminAPI::CloseShard + +#### Close a shard given a shard ID + +##### Headers + +| name | example | +|----------------|--------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.admin.v1.AdminAPI::CloseShard | + +##### Example payload + +```json +{ + "shard_id": 0 +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.admin.v1.AdminAPI::CloseShard' \ + -d \ + '{ + "shard_id": 0 + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.admin.v1.AdminAPI::CountDLQMessages + +#### Count DLQ messages + +##### Headers + +| name | example | +|----------------|--------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.admin.v1.AdminAPI::CountDLQMessages | + +##### Example payload + +None + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.admin.v1.AdminAPI::CountDLQMessages' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "history": [] +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.admin.v1.AdminAPI::DescribeCluster + +#### Describe cluster information + +##### Headers + +| name | example | +|----------------|-------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.admin.v1.AdminAPI::DescribeCluster | + +##### Example payload + +None + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.admin.v1.AdminAPI::DescribeCluster' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "supportedClientVersions": { + "goSdk": "1.7.0", + "javaSdk": "1.5.0" + }, + "membershipInfo": { + "currentHost": { + "identity": "127.0.0.1:7933" + }, + "reachableMembers": [ + "127.0.0.1:7933", + "127.0.0.1:7934", + "127.0.0.1:7935", + "127.0.0.1:7939" + ], + "rings": [ + { + "role": "cadence-frontend", + "memberCount": 1, + "members": [ + { + "identity": "127.0.0.1:7933" + } + ] + }, + { + "role": "cadence-history", + "memberCount": 1, + "members": [ + { + "identity": "127.0.0.1:7934" + } + ] + }, + { + "role": "cadence-matching", + "memberCount": 1, + "members": [ + { + "identity": "127.0.0.1:7935" + } + ] + }, + { + "role": "cadence-worker", + "memberCount": 1, + "members": [ + { + "identity": "127.0.0.1:7939" + } + ] + } + ] + }, + "persistenceInfo": { + "historyStore": { + "backend": "shardedNosql" + }, + "visibilityStore": { + "backend": "cassandra", + "features": [ + { + "key": "advancedVisibilityEnabled" + } + ] + } + } +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.admin.v1.AdminAPI::DescribeHistoryHost + +#### Describe internal information of history host + +##### Headers + +| name | example | +|----------------|-----------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.admin.v1.AdminAPI::DescribeHistoryHost | + +##### Example payload + +```json +{ + "host_address": "127.0.0.1:7934" +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.admin.v1.AdminAPI::DescribeHistoryHost' \ + -d \ + '{ + "host_address": "127.0.0.1:7934" + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "numberOfShards": 4, + "domainCache": { + "numOfItemsInCacheByID": 5, + "numOfItemsInCacheByName": 5 + }, + "shardControllerStatus": "started", + "address": "127.0.0.1:7934" +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.admin.v1.AdminAPI::DescribeShardDistribution + +#### List shard distribution + +##### Headers + +| name | example | +|----------------|-----------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.admin.v1.AdminAPI::DescribeShardDistribution | + +##### Example payload + +```json +{ + "page_size": 100, + "page_id": 0 +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.admin.v1.AdminAPI::DescribeShardDistribution' \ + -d \ + '{ + "page_size": 100, + "page_id": 0 + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "numberOfShards": 4, + "shards": { + "0": "127.0.0.1:7934", + "1": "127.0.0.1:7934", + "2": "127.0.0.1:7934", + "3": "127.0.0.1:7934" + } +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.admin.v1.AdminAPI::DescribeWorkflowExecution + +#### Describe internal information of workflow execution + +##### Headers + +| name | example | +|----------------|-----------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.admin.v1.AdminAPI::DescribeWorkflowExecution | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "cc09d5dd-b2fa-46d8-b426-54c96b12d18f" + } +} +``` + +`run_id` is optional and allows to describe a specific run. + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.admin.v1.AdminAPI::DescribeWorkflowExecution' \ + -d \ + '{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "cc09d5dd-b2fa-46d8-b426-54c96b12d18f" + } + }' | tr -d '\' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "shardId": 3, + "historyAddr": "127.0.0.1:7934", + "mutableStateInDatabase": { + "ActivityInfos": {}, + "TimerInfos": {}, + "ChildExecutionInfos": {}, + "RequestCancelInfos": {}, + "SignalInfos": {}, + "SignalRequestedIDs": {}, + "ExecutionInfo": { + "DomainID": "d7aff879-f524-43a8-b340-5a223a69d75b", + "WorkflowID": "sample-workflow-id", + "RunID": "cc09d5dd-b2fa-46d8-b426-54c96b12d18f", + "FirstExecutionRunID": "cc09d5dd-b2fa-46d8-b426-54c96b12d18f", + "ParentDomainID": "", + "ParentWorkflowID": "", + "ParentRunID": "", + "InitiatedID": -7, + "CompletionEventBatchID": 3, + "CompletionEvent": null, + "TaskList": "sample-task-list", + "WorkflowTypeName": "sample-workflow-type", + "WorkflowTimeout": 11, + "DecisionStartToCloseTimeout": 10, + "ExecutionContext": null, + "State": 2, + "CloseStatus": 6, + "LastFirstEventID": 3, + "LastEventTaskID": 8388614, + "NextEventID": 4, + "LastProcessedEvent": -23, + "StartTimestamp": "2023-09-08T05:13:04.24Z", + "LastUpdatedTimestamp": "2023-09-08T05:13:15.247Z", + "CreateRequestID": "8049b932-6c2f-415a-9bb2-241dcf4cfc9c", + "SignalCount": 0, + "DecisionVersion": 0, + "DecisionScheduleID": 2, + "DecisionStartedID": -23, + "DecisionRequestID": "emptyUuid", + "DecisionTimeout": 10, + "DecisionAttempt": 0, + "DecisionStartedTimestamp": 0, + "DecisionScheduledTimestamp": 1694149984240504000, + "DecisionOriginalScheduledTimestamp": 1694149984240503000, + "CancelRequested": false, + "CancelRequestID": "", + "StickyTaskList": "", + "StickyScheduleToStartTimeout": 0, + "ClientLibraryVersion": "", + "ClientFeatureVersion": "", + "ClientImpl": "", + "AutoResetPoints": {}, + "Memo": null, + "SearchAttributes": null, + "PartitionConfig": null, + "Attempt": 0, + "HasRetryPolicy": false, + "InitialInterval": 0, + "BackoffCoefficient": 0, + "MaximumInterval": 0, + "ExpirationTime": "0001-01-01T00:00:00Z", + "MaximumAttempts": 0, + "NonRetriableErrors": null, + "BranchToken": null, + "CronSchedule": "", + "IsCron": false, + "ExpirationSeconds": 0 + }, + "ExecutionStats": null, + "BufferedEvents": [], + "VersionHistories": { + "CurrentVersionHistoryIndex": 0, + "Histories": [ + { + "BranchToken": "WQsACgAAACRjYzA5ZDVkZC1iMmZhLTQ2ZDgtYjQyNi01NGM5NmIxMmQxOGYLABQAAAAkYWM5YmIwMmUtMjllYy00YWEyLTlkZGUtZWQ0YWU1NWRhMjlhDwAeDAAAAAAA", + "Items": [ + { + "EventID": 3, + "Version": 0 + } + ] + } + ] + }, + "ReplicationState": null, + "Checksum": { + "Version": 0, + "Flavor": 0, + "Value": null + } + } +} +``` + +
+ +------------------------------------------------------------------------------------------ + +### Domain API + +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.DomainAPI::DescribeDomain + +#### Describe existing workflow domain + +##### Headers + +| name | example | +|----------------|-----------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.DomainAPI::DescribeDomain | + +##### Example payload + +```json +{ + "name": "sample-domain", + "uuid": "d7aff879-f524-43a8-b340-5a223a69d75b" +} +``` + +`uuid` of the domain is optional. + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.DomainAPI::DescribeDomain' \ + -d \ + '{ + "name": "sample-domain" + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "domain": { + "id": "d7aff879-f524-43a8-b340-5a223a69d75b", + "name": "sample-domain", + "status": "DOMAIN_STATUS_REGISTERED", + "data": {}, + "workflowExecutionRetentionPeriod": "259200s", + "badBinaries": { + "binaries": {} + }, + "historyArchivalStatus": "ARCHIVAL_STATUS_ENABLED", + "historyArchivalUri": "file:///tmp/cadence_archival/development", + "visibilityArchivalStatus": "ARCHIVAL_STATUS_ENABLED", + "visibilityArchivalUri": "file:///tmp/cadence_vis_archival/development", + "activeClusterName": "cluster0", + "clusters": [ + { + "clusterName": "cluster0" + } + ], + "isGlobalDomain": true, + "isolationGroups": {} + } +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.DomainAPI::ListDomains + +#### List all domains in the cluster + +##### Headers + +| name | example | +|----------------|--------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.DomainAPI::ListDomains | + +##### Example payload + +```json +{ + "page_size": 100 +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.DomainAPI::ListDomains' \ + -d \ + '{ + "page_size": 100 + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "domains": [ + { + "id": "3116607e-419b-4783-85fc-47726a4c3fe9", + "name": "cadence-batcher", + "status": "DOMAIN_STATUS_REGISTERED", + "description": "Cadence internal system domain", + "data": {}, + "workflowExecutionRetentionPeriod": "604800s", + "badBinaries": { + "binaries": {} + }, + "historyArchivalStatus": "ARCHIVAL_STATUS_DISABLED", + "visibilityArchivalStatus": "ARCHIVAL_STATUS_DISABLED", + "activeClusterName": "cluster0", + "clusters": [ + { + "clusterName": "cluster0" + } + ], + "failoverVersion": "-24", + "isolationGroups": {} + }, + { + "id": "59c51119-1b41-4a28-986d-d6e377716f82", + "name": "cadence-shadower", + "status": "DOMAIN_STATUS_REGISTERED", + "description": "Cadence internal system domain", + "data": {}, + "workflowExecutionRetentionPeriod": "604800s", + "badBinaries": { + "binaries": {} + }, + "historyArchivalStatus": "ARCHIVAL_STATUS_DISABLED", + "visibilityArchivalStatus": "ARCHIVAL_STATUS_DISABLED", + "activeClusterName": "cluster0", + "clusters": [ + { + "clusterName": "cluster0" + } + ], + "failoverVersion": "-24", + "isolationGroups": {} + }, + { + "id": "32049b68-7872-4094-8e63-d0dd59896a83", + "name": "cadence-system", + "status": "DOMAIN_STATUS_REGISTERED", + "description": "cadence system workflow domain", + "ownerEmail": "cadence-dev-group@uber.com", + "data": {}, + "workflowExecutionRetentionPeriod": "259200s", + "badBinaries": { + "binaries": {} + }, + "historyArchivalStatus": "ARCHIVAL_STATUS_DISABLED", + "visibilityArchivalStatus": "ARCHIVAL_STATUS_DISABLED", + "activeClusterName": "cluster0", + "clusters": [ + { + "clusterName": "cluster0" + } + ], + "failoverVersion": "-24", + "isolationGroups": {} + }, + { + "id": "d7aff879-f524-43a8-b340-5a223a69d75b", + "name": "sample-domain", + "status": "DOMAIN_STATUS_REGISTERED", + "data": {}, + "workflowExecutionRetentionPeriod": "259200s", + "badBinaries": { + "binaries": {} + }, + "historyArchivalStatus": "ARCHIVAL_STATUS_ENABLED", + "historyArchivalUri": "file:///tmp/cadence_archival/development", + "visibilityArchivalStatus": "ARCHIVAL_STATUS_ENABLED", + "visibilityArchivalUri": "file:///tmp/cadence_vis_archival/development", + "activeClusterName": "cluster0", + "clusters": [ + { + "clusterName": "cluster0" + } + ], + "isGlobalDomain": true, + "isolationGroups": {} + } + ], + "nextPageToken": "" +} +``` + +
+ +------------------------------------------------------------------------------------------ + +### Meta API + +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.MetaAPI::Health + +#### Health check + +##### Headers + +| name | example | +|----------------|-------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.MetaAPI::Health | + +##### Example payload + +None + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.MetaAPI::Health' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "ok": true, + "message": "OK" +} +``` + +
+ +------------------------------------------------------------------------------------------ + +### Visibility API + +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.VisibilityAPI::GetSearchAttributes + +#### Get search attributes + +##### Headers + +| name | example | +|----------------|--------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.VisibilityAPI::GetSearchAttributes | + +##### Example payload + +None + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.VisibilityAPI::GetSearchAttributes' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "keys": { + "BinaryChecksums": "INDEXED_VALUE_TYPE_KEYWORD", + "CadenceChangeVersion": "INDEXED_VALUE_TYPE_KEYWORD", + "CloseStatus": "INDEXED_VALUE_TYPE_INT", + "CloseTime": "INDEXED_VALUE_TYPE_INT", + "CustomBoolField": "INDEXED_VALUE_TYPE_BOOL", + "CustomDatetimeField": "INDEXED_VALUE_TYPE_DATETIME", + "CustomDomain": "INDEXED_VALUE_TYPE_KEYWORD", + "CustomDoubleField": "INDEXED_VALUE_TYPE_DOUBLE", + "CustomIntField": "INDEXED_VALUE_TYPE_INT", + "CustomKeywordField": "INDEXED_VALUE_TYPE_KEYWORD", + "CustomStringField": "INDEXED_VALUE_TYPE_STRING", + "DomainID": "INDEXED_VALUE_TYPE_KEYWORD", + "ExecutionTime": "INDEXED_VALUE_TYPE_INT", + "HistoryLength": "INDEXED_VALUE_TYPE_INT", + "IsCron": "INDEXED_VALUE_TYPE_KEYWORD", + "NewKey": "INDEXED_VALUE_TYPE_KEYWORD", + "NumClusters": "INDEXED_VALUE_TYPE_INT", + "Operator": "INDEXED_VALUE_TYPE_KEYWORD", + "Passed": "INDEXED_VALUE_TYPE_BOOL", + "RolloutID": "INDEXED_VALUE_TYPE_KEYWORD", + "RunID": "INDEXED_VALUE_TYPE_KEYWORD", + "ShardID": "INDEXED_VALUE_TYPE_INT", + "StartTime": "INDEXED_VALUE_TYPE_INT", + "TaskList": "INDEXED_VALUE_TYPE_KEYWORD", + "TestNewKey": "INDEXED_VALUE_TYPE_STRING", + "UpdateTime": "INDEXED_VALUE_TYPE_INT", + "WorkflowID": "INDEXED_VALUE_TYPE_KEYWORD", + "WorkflowType": "INDEXED_VALUE_TYPE_KEYWORD", + "addon": "INDEXED_VALUE_TYPE_KEYWORD", + "addon-type": "INDEXED_VALUE_TYPE_KEYWORD", + "environment": "INDEXED_VALUE_TYPE_KEYWORD", + "project": "INDEXED_VALUE_TYPE_KEYWORD", + "service": "INDEXED_VALUE_TYPE_KEYWORD", + "user": "INDEXED_VALUE_TYPE_KEYWORD" + } +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.VisibilityAPI::ListClosedWorkflowExecutions + +#### List closed workflow executions in a domain + +##### Headers + +| name | example | +|----------------|-----------------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.VisibilityAPI::ListClosedWorkflowExecutions | + +##### Example payloads + +`startTimeFilter` is required while `executionFilter` and `typeFilter` are optional. + +```json +{ + "domain": "sample-domain", + "start_time_filter": { + "earliest_time": "2023-01-01T00:00:00Z", + "latest_time": "2023-12-31T00:00:00Z" + } +} +``` + +```json +{ + "domain": "sample-domain", + "start_time_filter": { + "earliest_time": "2023-01-01T00:00:00Z", + "latest_time": "2023-12-31T00:00:00Z" + }, + "execution_filter": { + "workflow_id": "sample-workflow-id", + "run_id": "71c3d47b-454a-4315-97c7-15355140094b" + } +} +``` + +```json +{ + "domain": "sample-domain", + "start_time_filter": { + "earliest_time": "2023-01-01T00:00:00Z", + "latest_time": "2023-12-31T00:00:00Z" + }, + "type_filter": { + "name": "sample-workflow-type" + } +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.VisibilityAPI::ListClosedWorkflowExecutions' \ + -d \ + '{ + "domain": "sample-domain", + "start_time_filter": { + "earliest_time": "2023-01-01T00:00:00Z", + "latest_time": "2023-12-31T00:00:00Z" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "executions": [ + { + "workflowExecution": { + "workflowId": "sample-workflow-id", + "runId": "71c3d47b-454a-4315-97c7-15355140094b" + }, + "type": { + "name": "sample-workflow-type" + }, + "startTime": "2023-09-08T06:31:18.778Z", + "closeTime": "2023-09-08T06:32:18.782Z", + "closeStatus": "WORKFLOW_EXECUTION_CLOSE_STATUS_TIMED_OUT", + "historyLength": "5", + "executionTime": "2023-09-08T06:31:18.778Z", + "memo": {}, + "searchAttributes": { + "indexedFields": {} + }, + "taskList": "sample-task-list" + } + ], + "nextPageToken": "" +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.VisibilityAPI::ListOpenWorkflowExecutions + +#### List open workflow executions in a domain + +##### Headers + +| name | example | +|----------------|---------------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.VisibilityAPI::ListOpenWorkflowExecutions | + +##### Example payloads + +`startTimeFilter` is required while `executionFilter` and `typeFilter` are optional. + +```json +{ + "domain": "sample-domain", + "start_time_filter": { + "earliest_time": "2023-01-01T00:00:00Z", + "latest_time": "2023-12-31T00:00:00Z" + } +} +``` + +```json +{ + "domain": "sample-domain", + "start_time_filter": { + "earliest_time": "2023-01-01T00:00:00Z", + "latest_time": "2023-12-31T00:00:00Z" + }, + "execution_filter": { + "workflow_id": "sample-workflow-id", + "run_id": "71c3d47b-454a-4315-97c7-15355140094b" + } +} +``` + +```json +{ + "domain": "sample-domain", + "start_time_filter": { + "earliest_time": "2023-01-01T00:00:00Z", + "latest_time": "2023-12-31T00:00:00Z" + }, + "type_filter": { + "name": "sample-workflow-type" + } +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.VisibilityAPI::ListOpenWorkflowExecutions' \ + -d \ + '{ + "domain": "sample-domain", + "start_time_filter": { + "earliest_time": "2023-01-01T00:00:00Z", + "latest_time": "2023-12-31T00:00:00Z" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "executions": [ + { + "workflowExecution": { + "workflowId": "sample-workflow-id", + "runId": "5dbabeeb-82a2-41ed-bf55-dc732a4d46ce" + }, + "type": { + "name": "sample-workflow-type" + }, + "startTime": "2023-09-12T02:17:46.596Z", + "executionTime": "2023-09-12T02:17:46.596Z", + "memo": {}, + "searchAttributes": { + "indexedFields": {} + }, + "taskList": "sample-task-list" + } + ], + "nextPageToken": "" +} +``` + +
+ +------------------------------------------------------------------------------------------ + +### Workflow API + +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::DescribeTaskList + +#### Describe pollers info of tasklist + +##### Headers + +| name | example | +|----------------|---------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::DescribeTaskList | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "task_list": { + "name": "sample-task-list", + "kind": 1 + }, + "task_list_type": 1, + "include_task_list_status": true +} +``` + +`task_list` kind is optional. + +Task list kinds + +| type | value | +|--------------------|-------| +| TaskListKindNormal | 1 | +| TaskListKindSticky | 2 | + +Task list types + +| type | value | +|----------------------|-------| +| TaskListTypeDecision | 1 | +| TaskListTypeActivity | 2 | + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::DescribeTaskList' \ + -d \ + '{ + "domain": "sample-domain", + "task_list": { + "name": "sample-task-list", + "kind": 1 + }, + "task_list_type": 1, + "include_task_list_status": true + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "taskListStatus": { + "readLevel": "200000", + "ratePerSecond": 100000, + "taskIdBlock": { + "startId": "200001", + "endId": "300000" + } + } +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::DescribeWorkflowExecution + +#### Describe a workflow execution + +##### Headers + +| name | example | +|----------------|------------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::DescribeWorkflowExecution | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "5dbabeeb-82a2-41ed-bf55-dc732a4d46ce" + } +} +``` + +`run_id` is optional and allows to describe a specific run. + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::DescribeWorkflowExecution' \ + -d \ + '{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "5dbabeeb-82a2-41ed-bf55-dc732a4d46ce" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "executionConfiguration": { + "taskList": { + "name": "sample-task-list" + }, + "executionStartToCloseTimeout": "11s", + "taskStartToCloseTimeout": "10s" + }, + "workflowExecutionInfo": { + "workflowExecution": { + "workflowId": "sample-workflow-id", + "runId": "5dbabeeb-82a2-41ed-bf55-dc732a4d46ce" + }, + "type": { + "name": "sample-workflow-type" + }, + "startTime": "2023-09-12T02:17:46.596Z", + "closeTime": "2023-09-12T02:17:57.602707Z", + "closeStatus": "WORKFLOW_EXECUTION_CLOSE_STATUS_TIMED_OUT", + "historyLength": "3", + "executionTime": "2023-09-12T02:17:46.596Z", + "memo": {}, + "searchAttributes": {}, + "autoResetPoints": {} + }, + "pendingDecision": { + "state": "PENDING_DECISION_STATE_SCHEDULED", + "scheduledTime": "2023-09-12T02:17:46.596982Z", + "originalScheduledTime": "2023-09-12T02:17:46.596982Z" + } +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::GetClusterInfo + +#### Get supported client versions for the cluster + +##### Headers + +| name | example | +|----------------|-------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::GetClusterInfo | + +##### Example payload + +None + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::GetClusterInfo' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "supportedClientVersions": { + "goSdk": "1.7.0", + "javaSdk": "1.5.0" + } +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::GetTaskListsByDomain + +#### Get the task lists in a domain + +##### Headers + +| name | example | +|----------------|-------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::GetTaskListsByDomain | + +##### Example payload + +```json +{ + "domain": "sample-domain" +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::GetTaskListsByDomain' \ + -d \ + '{ + "domain": "sample-domain" + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "decisionTaskListMap": {}, + "activityTaskListMap": {} +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::GetWorkflowExecutionHistory + +#### Get the history of workflow executions + +##### Headers + +| name | example | +|----------------|--------------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::GetWorkflowExecutionHistory | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id" + } +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::GetWorkflowExecutionHistory' \ + -d \ + '{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "history": { + "events": [ + { + "eventId": "1", + "eventTime": "2023-09-12T05:34:46.107550Z", + "taskId": "9437321", + "workflowExecutionStartedEventAttributes": { + "workflowType": { + "name": "sample-workflow-type" + }, + "taskList": { + "name": "sample-task-list" + }, + "input": { + "data": "IkN1cmwhIg==" + }, + "executionStartToCloseTimeout": "61s", + "taskStartToCloseTimeout": "60s", + "originalExecutionRunId": "fd7c2283-79dd-458c-8306-e2d1d8217613", + "identity": "client-name-visible-in-history", + "firstExecutionRunId": "fd7c2283-79dd-458c-8306-e2d1d8217613", + "firstDecisionTaskBackoff": "0s" + } + }, + { + "eventId": "2", + "eventTime": "2023-09-12T05:34:46.107565Z", + "taskId": "9437322", + "decisionTaskScheduledEventAttributes": { + "taskList": { + "name": "sample-task-list" + }, + "startToCloseTimeout": "60s" + } + }, + { + "eventId": "3", + "eventTime": "2023-09-12T05:34:59.184511Z", + "taskId": "9437330", + "workflowExecutionCancelRequestedEventAttributes": { + "cause": "dummy", + "identity": "client-name-visible-in-history" + } + }, + { + "eventId": "4", + "eventTime": "2023-09-12T05:35:47.112156Z", + "taskId": "9437332", + "workflowExecutionTimedOutEventAttributes": { + "timeoutType": "TIMEOUT_TYPE_START_TO_CLOSE" + } + } + ] + } +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::ListTaskListPartitions + +#### List all the task list partitions and the hostname for partitions + +##### Headers + +| name | example | +|----------------|---------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::ListTaskListPartitions | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "task_list": { + "name": "sample-task-list" + } +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::ListTaskListPartitions' \ + -d \ + '{ + "domain": "sample-domain", + "task_list": { + "name": "sample-task-list" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "activityTaskListPartitions": [ + { + "key": "sample-task-list", + "ownerHostName": "127.0.0.1:7935" + } + ], + "decisionTaskListPartitions": [ + { + "key": "sample-task-list", + "ownerHostName": "127.0.0.1:7935" + } + ] +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::RefreshWorkflowTasks + +#### Refresh all the tasks of a workflow + +##### Headers + +| name | example | +|----------------|-------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::RefreshWorkflowTasks | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "b7973fb8-2229-4fe7-ad70-c919c1ae8774" + } +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::RefreshWorkflowTasks' \ + -d \ + '{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "b7973fb8-2229-4fe7-ad70-c919c1ae8774" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::RequestCancelWorkflowExecution + +#### Cancel a workflow execution + +##### Headers + +| name | example | +|----------------|-----------------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::RequestCancelWorkflowExecution | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "b7973fb8-2229-4fe7-ad70-c919c1ae8774" + }, + "request_id": "8049B932-6C2F-415A-9BB2-241DCF4CFC9C", + "cause": "dummy", + "identity": "client-name-visible-in-history", + "first_execution_run_id": "b7973fb8-2229-4fe7-ad70-c919c1ae8774" +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::RequestCancelWorkflowExecution' \ + -d \ + '{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "fd7c2283-79dd-458c-8306-e2d1d8217613" + }, + "request_id": "8049B932-6C2F-415A-9BB2-241DCF4CFC9C", + "cause": "dummy", + "identity": "client-name-visible-in-history", + "first_execution_run_id": "fd7c2283-79dd-458c-8306-e2d1d8217613" + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::RestartWorkflowExecution + +#### Restart a previous workflow execution + +##### Headers + +| name | example | +|----------------|-----------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::RestartWorkflowExecution | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "0f95ad5b-03bc-4c6b-8cf0-1f3ea08eb86a" + }, + "identity": "client-name-visible-in-history", + "reason": "dummy" +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::RestartWorkflowExecution' \ + -d \ + '{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "0f95ad5b-03bc-4c6b-8cf0-1f3ea08eb86a" + }, + "identity": "client-name-visible-in-history", + "reason": "dummy" + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "runId": "82914458-3221-42b4-ae54-2e66dff864f7" +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::SignalWithStartWorkflowExecution + +#### Signal the current open workflow if exists, or attempt to start a new run based on IDResuePolicy and signals it + +##### Headers + +| name | example | +|----------------|-------------------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::SignalWithStartWorkflowExecution | + +##### Example payload + +```json +{ + "start_request": { + "domain": "sample-domain", + "workflow_id": "sample-workflow-id", + "execution_start_to_close_timeout": "61s", + "task_start_to_close_timeout": "60s", + "workflow_type": { + "name": "sample-workflow-type" + }, + "task_list": { + "name": "sample-task-list" + }, + "identity": "client-name-visible-in-history", + "request_id": "8049B932-6C2F-415A-9BB2-241DCF4CFC9C", + "input": { + "data": "IkN1cmwhIg==" + } + }, + "signal_name": "channelA", + "signal_input": { + "data": "MTA=" + } +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::SignalWithStartWorkflowExecution' \ + -d \ + '{ + "start_request": { + "domain": "sample-domain", + "workflow_id": "sample-workflow-id", + "execution_start_to_close_timeout": "61s", + "task_start_to_close_timeout": "60s", + "workflow_type": { + "name": "sample-workflow-type" + }, + "task_list": { + "name": "sample-task-list" + }, + "identity": "client-name-visible-in-history", + "request_id": "8049B932-6C2F-415A-9BB2-241DCF4CFC9C", + "input": { + "data": "IkN1cmwhIg==" + } + }, + "signal_name": "channelA", + "signal_input": { + "data": "MTA=" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "runId": "cc09d5dd-b2fa-46d8-b426-54c96b12d18f" +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::SignalWorkflowExecution + +#### Signal a workflow execution + +##### Headers + +| name | example | +|----------------|----------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::SignalWorkflowExecution | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "cc09d5dd-b2fa-46d8-b426-54c96b12d18f" + }, + "signal_name": "channelA", + "signal_input": { + "data": "MTA=" + } +} +``` + +`run_id` is optional and allows to signal a specific run. + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::SignalWorkflowExecution' \ + -d \ + '{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id" + }, + "signal_name": "channelA", + "signal_input": { + "data": "MTA=" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::StartWorkflowExecution + +#### Start a new workflow execution + +##### Headers + +| name | example | +|----------------|---------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::StartWorkflowExecution | + +##### Example payload + +```json +{ + "domain": "sample-domain", + "workflow_id": "sample-workflow-id", + "execution_start_to_close_timeout": "61s", + "task_start_to_close_timeout": "60s", + "workflow_type": { + "name": "sample-workflow-type" + }, + "task_list": { + "name": "sample-task-list" + }, + "identity": "client-name-visible-in-history", + "request_id": "8049B932-6C2F-415A-9BB2-241DCF4CFC9C", + "input": { + "data": "IkN1cmwhIg==" + } +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::StartWorkflowExecution' \ + -d \ + '{ + "domain": "sample-domain", + "workflow_id": "sample-workflow-id", + "execution_start_to_close_timeout": "61s", + "task_start_to_close_timeout": "60s", + "workflow_type": { + "name": "sample-workflow-type" + }, + "task_list": { + "name": "sample-task-list" + }, + "identity": "client-name-visible-in-history", + "request_id": "8049B932-6C2F-415A-9BB2-241DCF4CFC9C", + "input": { + "data": "IkN1cmwhIg==" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{ + "runId": "cc09d5dd-b2fa-46d8-b426-54c96b12d18f" +} +``` + +
+ +------------------------------------------------------------------------------------------ + +
+POST uber.cadence.api.v1.WorkflowAPI::TerminateWorkflowExecution + +#### Terminate a new workflow execution + +##### Headers + +| name | example | +|----------------|-------------------------------------------------------------| +| context-ttl-ms | 2000 | +| rpc-caller | curl-client | +| rpc-service | cadence-frontend | +| rpc-encoding | json | +| rpc-procedure | uber.cadence.api.v1.WorkflowAPI::TerminateWorkflowExecution | + +##### Example payloads + +```json +{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id" + } +} +``` + +```json +{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id", + "run_id": "0f95ad5b-03bc-4c6b-8cf0-1f3ea08eb86a" + }, + "reason": "dummy", + "identity": "client-name-visible-in-history", + "first_execution_run_id": "0f95ad5b-03bc-4c6b-8cf0-1f3ea08eb86a" +} +``` + +##### Example cURL + +```bash +curl -X POST http://0.0.0.0:8800 \ + -H 'context-ttl-ms: 2000' \ + -H 'rpc-caller: curl-client' \ + -H 'rpc-service: cadence-frontend' \ + -H 'rpc-encoding: json' \ + -H 'rpc-procedure: uber.cadence.api.v1.WorkflowAPI::TerminateWorkflowExecution' \ + -d \ + '{ + "domain": "sample-domain", + "workflow_execution": { + "workflow_id": "sample-workflow-id" + } + }' +``` + +##### Example successful response + +HTTP code: 200 + +```json +{} +``` + +
+ +------------------------------------------------------------------------------------------ From de50e3752b66b70375f5dd54c70b3bcdd4953e0e Mon Sep 17 00:00:00 2001 From: "justin.weng" Date: Wed, 13 Sep 2023 15:02:53 +1000 Subject: [PATCH 2/3] Add reference to file --- src/.vuepress/config.js | 1 + src/docs/03-concepts/index.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 3bc5491b1..5ea3373c5 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -96,6 +96,7 @@ module.exports = { '03-concepts/07-archival', '03-concepts/08-cross-dc-replication', '03-concepts/09-search-workflows', + '03-concepts/10-http-api', ], }, { diff --git a/src/docs/03-concepts/index.md b/src/docs/03-concepts/index.md index 17ccd72e3..4d1497619 100644 --- a/src/docs/03-concepts/index.md +++ b/src/docs/03-concepts/index.md @@ -11,3 +11,5 @@ Cadence is a new developer friendly way to develop distributed applications. It borrows the core terminology from the workflow-automation space. So its concepts include [workflows](01-workflows/) and [activities](02-activities/). :workflow:Workflows: can react to [events](03-events/) and return internal state through [queries](04-queries/). The [deployment topology](05-topology/) explains how all these concepts are mapped to deployable software components. + +The [HTTP API reference](10-http-api/) describes how to use HTTP API to interact with Cadence server. From d882191aa36059562c24ae2edf20de4492ee9379 Mon Sep 17 00:00:00 2001 From: "justin.weng" Date: Fri, 8 Mar 2024 16:03:08 +1100 Subject: [PATCH 3/3] Update doco about using configstore --- src/docs/07-operation-guide/01-setup.md | 33 +++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/src/docs/07-operation-guide/01-setup.md b/src/docs/07-operation-guide/01-setup.md index 04c27d27c..89004bec6 100644 --- a/src/docs/07-operation-guide/01-setup.md +++ b/src/docs/07-operation-guide/01-setup.md @@ -37,7 +37,7 @@ There are quite many configs in Cadence. Here are the most basic configuration t | archival | This is for archival history feature, skip if you don’t need it. Go to [workflow archival](/docs/concepts/archival/#running-in-production) for how to configure archival in production | N/A | | blobstore | This is also for archival history feature Default cadence server is using file based blob store implementation. | N/A | | domainDefaults | default config for each domain. Right now only being used for Archival feature. | N/A | -| dynamicConfigClient | Dynamic config is a config manager that you can change config without restarting servers. It’s a good way for Cadence to keep high availability and make things easy to configure.

Default cadence server is using FileBasedClientConfig. But you can implement the dynamic config interface if you have a better way to manage.| Same as the sample development config | +| dynamicconfig (previously known as dynamicConfigClient) | Dynamic config is a config manager that enables you to change configs without restarting servers. It’s a good way for Cadence to keep high availability and make things easy to configure.

By default Cadence server uses `filebased` client which allows you to override default configs using a YAML file. However, this approach can be cumbersome in production environment because it's the operator's responsibility to sync the YAML files across Cadence nodes.

Therefore, we provide another option, `configstore` client, that stores config changes in the persistent data store for Cadence (e.g., Cassandra database) rather than the YAML file. This approach shifts the responsibility of syncing config changes from the operator to Cadence service. You can use Cadence CLI commands to list/get/update/restore config changes.

You can also implement the dynamic config interface if you have a better way to manage configs. | Same as the sample development config | | persistence | Configuration for data store / persistence layer.

Values of DefaultStore VisibilityStore AdvancedVisibilityStore should be keys of map DataStores.

DefaultStore is for core Cadence functionality.

VisibilityStore is for basic visibility feature

AdvancedVisibilityStore is for advanced visibility

Go to [advanced visibility](/docs/concepts/search-workflows/#running-in-production) for detailed configuration of advanced visibility. See [persistence documentation](https://github.com/uber/cadence/blob/master/docs/persistence.md) about using different database for Cadence| As explanation | ### The full list of static configuration @@ -124,7 +124,11 @@ NOTE 2: for .persistenceMaxQPS versus ` gets the value of a specific dynamic config +* `cadence admin config updc --dynamic_config_name --dynamic_config_value '{"Value": }'` updates the value of a specific dynamic config +* `cadence admin config resdc --dynamic_config_name ` restores a specific dynamic config to its default value ## Other Advanced Features * Go to [advanced visibility](/docs/concepts/search-workflows/#running-in-production) for how to configure advanced visibility in production.