Choosing the right Dapr API

The same job can often be done several ways across the Dapr building blocks. Use this guide to pick the right API when you start building. For an overview of every API and what it does, see Dapr APIs.

Decision guide

• Need a multi-step business process that has to survive crashes and may pause for hours or days? Reach for Workflow.
• Need per-entity state and behavior with single-threaded semantics, like a customer, a device, or a chat session? Reach for Actors.
• Need to call another app and get a response back? Use Service invocation. Don't reach for a queue.
• Need to broadcast an event to many subscribers, or decouple producer from consumer? Use Pub/Sub.
• Need to store and retrieve key-value data? Use State. If a single transaction needs to span several keys, use the State transaction API; if you need rich queries, prefer a state store with the query capability.
• Need to call an LLM with retries and provider-agnostic code? Use Conversation.
• Need to react to an external event source, or push data to an external system without writing a custom integration? Use Bindings.
• Need to run scheduled or delayed work durably? Use Jobs.
• Need to read configuration values at runtime and react to changes? Use Configuration.
• Need to resolve a credential at call time? Use Secrets.
• Need a mutex across replicas of the same app? Use Distributed lock (alpha).

Prefer the higher-level API

When two APIs both fit, prefer the higher-level one: Workflow over Jobs plus State, Service invocation over Pub/Sub-as-RPC, Actors over hand-rolled locking. The higher-level APIs encode the failure-handling rules you'd otherwise have to write yourself.

See also

• Dapr APIs: the full catalogue of building blocks and their managed options.
• Components: the YAML resources that bind each API to a backend.
• Workflow and Durable execution: the durable-orchestration layer built on top of these APIs.