Skip to main content

​
Introduction

The Cadence API is organized into three core services that work together to orchestrate distributed workflows:
  • Frontend Service: Public-facing API for workflow and domain management
  • History Service: Internal service managing workflow execution state and history
  • Matching Service: Internal service handling task distribution and polling

​
Service Architecture

​
API Services

​
Frontend Service

The Frontend Service is the primary entry point for Cadence clients. It provides APIs for:
  • Starting and managing workflow executions
  • Registering and managing domains
  • Querying workflow state and history
  • Polling for decision and activity tasks
  • Recording task completions and failures
View Frontend Service API →

​
History Service

The History Service maintains workflow execution state and event history. It handles:
  • Workflow execution lifecycle management
  • Event history persistence and retrieval
  • Mutable state management
  • Cross-cluster replication
  • Workflow reset and recovery operations
View History Service API →

​
Matching Service

The Matching Service coordinates task distribution between workflow workers and the Cadence cluster:
  • Task list management and partitioning
  • Long-polling for decision and activity tasks
  • Task routing and load balancing
  • Query workflow execution
View Matching Service API →

​
Type Definitions

Cadence uses strongly-typed request/response structures organized by functional area:

Workflow Types

Workflow execution, decision, and activity types

Domain Types

Domain configuration and replication types

Task Types

Decision task and activity task types

Common Types

Shared types used across all services

​
API Conventions

​
Request/Response Pattern

All Cadence APIs follow a consistent request/response pattern: 
func MethodName(ctx context.Context, request *types.MethodRequest) (*types.MethodResponse, error)

​
Error Handling

Cadence uses typed errors for well-known failure scenarios:
  • BadRequestError: Invalid request parameters
  • EntityNotExistsError: Requested entity not found
  • DomainNotActiveError: Domain is not active
  • ServiceBusyError: Service is throttling requests
  • WorkflowExecutionAlreadyStartedError: Workflow already running

​
Common Parameters

ParameterTypeDescription
DomainUUIDstringUnique identifier for the domain
DomainstringHuman-readable domain name
WorkflowExecutionobjectWorkflow ID and Run ID
TaskListobjectTask list name and type
IdentitystringWorker or client identity

​
Authentication & Authorization

Cadence supports pluggable authorization through the Authorization interface: 
type Authorization interface {
    Authorize(ctx context.Context, attributes *AuthorizationAttributes) (Result, error)
}
Authorization attributes include:
  • Domain name
  • API name
  • Permission type (Read/Write)
  • Request context

​
Rate Limiting

All services implement rate limiting at multiple levels:
  1. Global rate limiting: Per-service RPS limits
  2. Domain rate limiting: Per-domain RPS limits
  3. Worker rate limiting: Per-worker RPS limits
Rate limit errors return ServiceBusyError with retry-after information.

​
Protocol Support

Cadence services support multiple wire protocols:
  • Thrift: Legacy protocol for backward compatibility
  • gRPC: Modern protocol with better performance and streaming support
All type definitions in common/types are protocol-agnostic, with mappers handling conversion to/from wire formats.

​
SDK Integration

The API reference describes the server-side APIs. For client-side development, use the official Cadence SDKs: SDKs provide higher-level abstractions and handle:
  • Connection management
  • Automatic retries
  • Task polling and dispatch
  • Workflow and activity registration

​
Next Steps

Frontend Service

Explore public-facing workflow APIs

Type Definitions

Learn about core type definitions

Build docs developers (and LLMs) love

Get started for freeTalk to us