Pub/sub API reference

Detailed documentation on the pub/sub API

Publish a message to a given topic

This endpoint lets you publish data to multiple consumers who are listening on a topic. Dapr guarantees At-Least-Once semantics for this endpoint.

HTTP Request

  1. POST http://localhost:<daprPort>/v1.0/publish/<pubsubname>/<topic>[?<metadata>]

HTTP Response codes

CodeDescription
204Message delivered
403Message forbidden by access controls
404No pubsub name or topic given
500Delivery failed

URL Parameters

ParameterDescription
daprPortThe Dapr port
pubsubnameThe name of pubsub component
topicThe name of the topic
metadataQuery parameters for metadata as described below

Note, all URL parameters are case-sensitive.

  1. curl -X POST http://localhost:3500/v1.0/publish/pubsubName/deathStarStatus \
  2. -H "Content-Type: application/json" \
  3. -d '{
  4. "status": "completed"
  5. }'

Headers

The Content-Type header tells Dapr which content type your data adheres to when constructing a CloudEvent envelope. The Content-Type header value populates the datacontenttype field in the CloudEvent.

Unless specified, Dapr assumes text/plain. If your content type is JSON, use a Content-Type header with the value of application/json.

If you want to send your own custom CloudEvent, use the application/cloudevents+json value for the Content-Type header.

Metadata

Metadata can be sent via query parameters in the request’s URL. It must be prefixed with metadata., as shown below.

ParameterDescription
metadata.ttlInSecondsThe number of seconds for the message to expire, as described here
metadata.rawPayloadBoolean to determine if Dapr should publish the event without wrapping it as CloudEvent, as described here

Additional metadata parameters are available based on each pubsub component.

Publish multiple messages to a given topic

This endpoint lets you publish multiple messages to consumers who are listening on a topic.

HTTP Request

  1. POST http://localhost:<daprPort>/v1.0-alpha1/publish/bulk/<pubsubname>/<topic>[?<metadata>]

The request body should contain a JSON array of entries with:

  • Unique entry IDs
  • The event to publish
  • The content type of the event

If the content type for an event is not application/cloudevents+json, it is auto-wrapped as a CloudEvent (unless metadata.rawPayload is set to true).

Example:

  1. curl -X POST http://localhost:3500/v1.0-alpha1/publish/bulk/pubsubName/deathStarStatus \
  2. -H 'Content-Type: application/json' \
  3. -d '[
  4. {
  5. "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
  6. "event": "first text message",
  7. "contentType": "text/plain"
  8. },
  9. {
  10. "entryId": "b1f40bd6-4af2-11ed-b878-0242ac120002",
  11. "event": {
  12. "message": "second JSON message"
  13. },
  14. "contentType": "application/json"
  15. },
  16. ]'

Headers

The Content-Type header should always be set to application/json since the request body is a JSON array.

URL Parameters

ParameterDescription
daprPortThe Dapr port
pubsubnameThe name of pub/sub component
topicThe name of the topic
metadataQuery parameters for metadata

Metadata

Metadata can be sent via query parameters in the request’s URL. It must be prefixed with metadata., as shown in the table below.

ParameterDescription
metadata.rawPayloadBoolean to determine if Dapr should publish the messages without wrapping them as CloudEvent.
metadata.maxBulkPubBytesMaximum bytes to publish in a bulk publish request.

HTTP Response

HTTP StatusDescription
204All messages delivered
400Pub/sub does not exist
403Forbidden by access controls
500At least one message failed to be delivered

In case of a 500 status code, the response body will contain a JSON object containing a list of entries that failed to be delivered. For example from our request above, if the entry with event "first text message" failed to be delivered, the response would contain its entry ID and an error message from the underlying pub/sub component.

  1. {
  2. "failedEntries": [
  3. {
  4. "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
  5. "error": "some error message"
  6. },
  7. ],
  8. "errorCode": "ERR_PUBSUB_PUBLISH_MESSAGE"
  9. }

Optional Application (User Code) Routes

Provide a route for Dapr to discover topic subscriptions

Dapr will invoke the following endpoint on user code to discover topic subscriptions:

HTTP Request

  1. GET http://localhost:<appPort>/dapr/subscribe

URL Parameters

ParameterDescription
appPortThe application port

HTTP Response body

A JSON-encoded array of strings.

Example:

  1. [
  2. {
  3. "pubsubname": "pubsub",
  4. "topic": "newOrder",
  5. "routes": {
  6. "rules": [
  7. {
  8. "match": "event.type == order",
  9. "path": "/orders"
  10. }
  11. ]
  12. "default" : "/otherorders"
  13. },
  14. "metadata": {
  15. "rawPayload": "true"
  16. }
  17. }
  18. ]

Note, all subscription parameters are case-sensitive.

Metadata

Optionally, metadata can be sent via the request body.

ParameterDescription
rawPayloadboolean to subscribe to events that do not comply with CloudEvent specification, as described here

Provide route(s) for Dapr to deliver topic events

In order to deliver topic events, a POST call will be made to user code with the route specified in the subscription response. Under routes, you can provide rules that match a certain condition to a specific path when a message topic is received. You can also provide a default route for any rules that do not have a specific match.

The following example illustrates this point, considering a subscription for topic newOrder with route orders on port 3000: POST http://localhost:3000/orders

HTTP Request

  1. POST http://localhost:<appPort>/<path>

Note, all URL parameters are case-sensitive.

URL Parameters

ParameterDescription
appPortThe application port
pathRoute path from the subscription configuration

Expected HTTP Response

An HTTP 2xx response denotes successful processing of message.

For richer response handling, a JSON-encoded payload body with the processing status can be sent:

  1. {
  2. "status": "<status>"
  3. }
StatusDescription
SUCCESSMessage is processed successfully
RETRYMessage to be retried by Dapr
DROPWarning is logged and message is dropped
OthersError, message to be retried by Dapr

Dapr assumes that a JSON-encoded payload response without status field or an empty payload responses with HTTP 2xx is a SUCCESS.

The HTTP response might be different from HTTP 2xx. The following are Dapr’s behavior in different HTTP statuses:

HTTP StatusDescription
2xxmessage is processed as per status in payload (SUCCESS if empty; ignored if invalid payload).
404error is logged and message is dropped
otherwarning is logged and message to be retried

Subscribe multiple messages from a given topic

This allows you to subscribe to multiple messages from a broker when listening to a topic.

In order to receive messages in a bulk manner for a topic subscription, the application:

  • Needs to opt for bulkSubscribe while sending list of topics to be subscribed to
  • Optionally, can configure maxMessagesCount and/or maxAwaitDurationMs Refer to the Send and receive messages in bulk guide for more details on how to opt-in.

Expected HTTP Response for Bulk Subscribe

An HTTP 2xx response denotes that entries (individual messages) inside this bulk message have been processed by the application and Dapr will now check each EntryId status. A JSON-encoded payload body with the processing status against each entry needs to be sent:

  1. {
  2. "statuses":
  3. [
  4. {
  5. "entryId": "<entryId1>",
  6. "status": "<status>"
  7. },
  8. {
  9. "entryId": "<entryId2>",
  10. "status": "<status>"
  11. }
  12. ]
  13. }

Note: If an EntryId status is not found by Dapr in a response received from the application, that entry’s status is considered RETRY.

StatusDescription
SUCCESSMessage is processed successfully
RETRYMessage to be retried by Dapr
DROPWarning is logged and message is dropped

The HTTP response might be different from HTTP 2xx. The following are Dapr’s behavior in different HTTP statuses:

HTTP StatusDescription
2xxmessage is processed as per status in payload.
404error is logged and all messages are dropped
otherwarning is logged and all messages to be retried

Message envelope

Dapr pub/sub adheres to version 1.0 of CloudEvents.

Last modified October 11, 2024: Fixed typo (#4389) (fe17926)