From 2eedb519dc7e8b4e99b501a95d524e22ee9d6b57 Mon Sep 17 00:00:00 2001
From: Matthieu Gallien <matthieu.gallien@nextcloud.com>
Date: Fri, 4 Feb 2022 12:09:33 +0100
Subject: [PATCH] add documentation about the bulk upload protocol

Signed-off-by: Matthieu Gallien <matthieu.gallien@nextcloud.com>
---
 .../client_apis/WebDAV/bulkupload.rst         | 43 +++++++++++++++++++
 developer_manual/client_apis/WebDAV/index.rst |  1 +
 2 files changed, 44 insertions(+)
 create mode 100644 developer_manual/client_apis/WebDAV/bulkupload.rst

diff --git a/developer_manual/client_apis/WebDAV/bulkupload.rst b/developer_manual/client_apis/WebDAV/bulkupload.rst
new file mode 100644
index 000000000..6bee64a92
--- /dev/null
+++ b/developer_manual/client_apis/WebDAV/bulkupload.rst
@@ -0,0 +1,43 @@
+===================
+File bulk upload
+===================
+
+.. sectionauthor:: Matthieu Gallien <matthieu.gallien@nextcloud.com>
+
+Introduction
+------------
+Uploading many small files is often slower than what could be achieved because we do not
+use the whole network bandwidth. Nextcloud has a bulk upload API where you can upload
+many small files together in order to optimize the use of network bandwidth.
+
+Usage
+-----
+
+The API is only available for registered users of your instance. And uses the path:
+``<server>/remote.php/dav/bulk``.
+
+Starting a bulk upload
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A bulk upload is simply using a request structured as HTTP multipart with related mime type.
+
+Each file is then sent as one HTTP part.
+
+Each file inside an HTTP Part will need the following headers:
+
+* Content-Length: <file size>
+* Content-Type: <mimetype>
+* X-File-MD5: <md5 checksum>
+* X-File-Mtime: <modification time of file>
+* X-File-Path: <destination file path>
+
+The reply is a json document with the following structure:
+
+.. code-block:: JSON
+
+  {
+      "/small file.txt": {
+          "error": false,
+          "etag": "adb9aa24cbfa8e372c88431d1d99629a"
+      }
+  }
diff --git a/developer_manual/client_apis/WebDAV/index.rst b/developer_manual/client_apis/WebDAV/index.rst
index e389074d8..98268834a 100644
--- a/developer_manual/client_apis/WebDAV/index.rst
+++ b/developer_manual/client_apis/WebDAV/index.rst
@@ -12,4 +12,5 @@ Webdav
     trashbin
     versions
     chunking
+    bulkupload
     comments