From 12bbac91d47c5753e34e9dd84bda9dabeae02e66 Mon Sep 17 00:00:00 2001
From: Shubham Sharma <shubhash@microsoft.com>
Date: Wed, 14 Dec 2022 11:48:56 +0530
Subject: [PATCH] WIP publish docs

Signed-off-by: Shubham Sharma <shubhash@microsoft.com>
---
 .../building-blocks/pubsub/pubsub-bulk.md     | 11 ++++
 .../building-blocks/pubsub/pubsub-overview.md |  4 ++
 .../content/en/reference/api/pubsub_api.md    | 66 +++++++++++++++++++
 3 files changed, 81 insertions(+)
 create mode 100644 daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-bulk.md

diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-bulk.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-bulk.md
new file mode 100644
index 000000000..3375dfc8c
--- /dev/null
+++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-bulk.md
@@ -0,0 +1,11 @@
+---
+type: docs
+title: "Publishing & subscribing messages in bulk"
+linkTitle: "Bulk messages"
+weight: 2100
+description: "Learn how to send and receive multiple messages at once"
+---
+
+insert-introduction
+
+## Publishing messages in bulk
\ No newline at end of file
diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md
index 2b90adda6..7dae7663d 100644
--- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md
+++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/pubsub-overview.md
@@ -119,6 +119,10 @@ By default, all topic messages associated with an instance of a pub/sub componen
 
 Dapr can set a timeout message on a per-message basis, meaning that if the message is not read from the pub/sub component, then the message is discarded. This timeout message prevents a build up of unread messages. If a message has been in the queue longer than the configured TTL, it is marked as dead. For more information, read [pub/sub message TTL]({{< ref pubsub-message-ttl.md >}}).
 
+### Bulk messages
+
+Dapr supports sending and receiving multiple messages in a single request. This is useful for applications that need to send or receive a large number of messages at once. For more information, read [pub/sub bulk messages]({{< ref pubsub-bulk.md >}}).
+
 ## Try out pub/sub
 
 ### Quickstarts and tutorials
diff --git a/daprdocs/content/en/reference/api/pubsub_api.md b/daprdocs/content/en/reference/api/pubsub_api.md
index f4d8e47fa..69d7c813b 100644
--- a/daprdocs/content/en/reference/api/pubsub_api.md
+++ b/daprdocs/content/en/reference/api/pubsub_api.md
@@ -64,6 +64,72 @@ Parameter | Description
 
 > 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
+
+```
+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. Example:
+
+```json
+[
+    {
+        "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
+        "event":  "first",
+        "contentType": "text/plain"
+    },
+    {
+        "entryId": "b1f40bd6-4af2-11ed-b878-0242ac120002",
+        "event":  {
+            "message": "second"   
+        },
+        "contentType": "application/json"
+    },
+]
+```
+
+Just like the publish endpoint, the events are auto-wrapped as CloudEvents if `rawPayload` metadata is not set to true. The `contentType` field is optional and defaults to `text/plain`.
+
+### Headers
+
+The `Content-Type` header should be set to `application/json`.
+
+### Metadata
+
+Metadata can be sent via query parameters in the request's URL. If must be prefixed with `metadata.` as shown below.
+
+|**Parameter**|**Description**|
+|--|--|
+|`metadata.rawPayload`|Boolean to determine if Dapr should publish the messages without wrapping them as CloudEvent.|
+|`metadata.maxBulkPubBytes`|Maximum bytes to publish in a bulk publish request.|
+
+
+#### HTTP Response
+
+|**Code**|**Description**|
+|--|--|
+|204|All messages delivered|
+|400|Pubsub does not exist|
+|403|Forbidden by access controls|
+|500|At least one message failed to be delivered|
+
+The response body is a JSON containing a list of failed messages. Example:
+
+```json
+[
+    {
+        "entryId": "ae6bf7c6-4af2-11ed-b878-0242ac120002",
+        "error": "error message",
+        "status": "FAIL",
+    }
+]
+```
+
 ## Optional Application (User Code) Routes
 
 ### Provide a route for Dapr to discover topic subscriptions