Merge pull request #12043 from nextcloud/feat/file_request

developer_manual/client_apis/OCS/ocs-share-api.rst

@@ -13,7 +13,7 @@ Local Shares
 ------------
 
 Get all Shares
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 Get all shares from the user.
 
@@ -28,7 +28,7 @@ Statuscodes:
 * 404 - couldn't fetch shares
 
 Get Shares from a specific file or folder
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Get all shares from a given file/folder.
 
@@ -50,7 +50,7 @@ Statuscodes:
 * 404 - file doesn't exist
 
 Get information about a known Share
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Get information about a given share.
 
@@ -67,7 +67,7 @@ Statuscodes:
 * 404 - share doesn't exist
 
 Create a new Share
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 
 Share a file/folder with a user/group or as public link.
 
@@ -84,7 +84,9 @@ Share a file/folder with a user/group or as public link.
 * POST Arguments: expireDate - (string) set a expire date for public link
   shares. This argument expects a well formatted date string, e.g. 'YYYY-MM-DD'
 * POST Arguments: note - (string) Adds a note for the share recipient.
+* POST Arguments: label - (string) Adds a label for the share recipient.
 * POST Arguments: attributes - (string) URI-encoded serialized JSON string for :ref:`share attributes<Share attributes>`
+* POST Arguments: sendMail - (string) send an email to the recipient after creation (true/false)
 * Mandatory fields: shareType, path and shareWith for shareType 0 or 1.
 
 * Result: XML containing the share ID (int) of the newly created share
@@ -97,7 +99,7 @@ Statuscodes:
 * 404 - file couldn't be shared
 
 Delete Share
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 Remove the given share.
 
@@ -112,7 +114,7 @@ Statuscodes:
 * 404 - file couldn't be deleted
 
 Update Share
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 Update a given share. Only one value can be updated per request.
 
@@ -129,6 +131,7 @@ Update a given share. Only one value can be updated per request.
   shares. This argument expects a well formatted date string, e.g. 'YYYY-MM-DD'
 * PUT Arguments: note - (string) Adds a note for the share recipient.
 * PUT Arguments: attributes - (string) serialized JSON string for :ref:`share attributes<Share attributes>`
+* PUT Arguments: sendMail - (string) send an email to the recipient. This will not send an email on its own. You will have to use the `send-email` endpoint to send the email. (true/false)
 
 .. note:: Only one of the update parameters can be specified at once.
 
@@ -142,26 +145,83 @@ Statuscodes:
 .. _Share attributes:
 
 Share attributes
-^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~
 
 Share attributes are used for more advanced flags like permissions.
 
+.. code-block:: json
+
+    [
+        { "scope": "permissions", "key": "download", "value": false }
+    ]
+
+.. warning:: Since Nextcloud 30, the `enabled` key have bee renamed to `value` and supports more than boolean.
+ 
+Download permission
+"""""""""""""""""""
+
 To remove the download permission from a share, use the following serialized string in the "attributes" parameter:
 
 .. code-block:: json
 
     [
-        {"scope":"permissions","key":"download","enabled":false}
+        { "scope": "permissions", "key": "download", "value": false }
     ]
 
+
 This will prevent users from downloading the files from the share.
 For specific file types like office files, it will still be possible to view the files using the appropriate viewer app,
 which itself will present the file in a way that downloading will not be allowed.
 
 By default when unset, the "download" attribute will be true and so the download permission will be granted.
 
-.. note:: There is currently only one share attribute "download" from the scope "permissions".
-   This attribute is only valid for user and group shares, not for public link shares.
+File request
+""""""""""""
+
+When creating a link or mail share, you can enable the file request feature.
+It will ask recipients to enter their name and all uploaded files will be stored in a
+separate folder with the provided name.
+
+.. code-block:: json
+
+    [
+        { "scope": "fileRequest", "key": "enabled", "value": true }
+    ]
+
+When creating the file request, you can also provide an array of emails.
+Traditionally, only one is allowed with the `shareWith` parameter,
+but you can provide a list of emails via attributes. This only works for MAIL shares.
+
+.. code-block:: json
+
+    [
+        { "scope": "fileRequest", "key": "enabled", "value": true },
+        { "scope": "shareWith", "key": "emails", "value": ["maria@company.com", "paul@company.com"] }
+    ]
+
+.. note:: You will have to provide an empty string as `shareWith` parameter when creating the share.
+   Updating or creating the share with those parameters, will NOT send an email to the recipients.
+   You will have to use the `send-email` endpoint to send the email.
+
+.. _Send email:
+
+Send email
+~~~~~~~~~~
+
+Send an email to the recipients of a share.
+
+* Syntax: /shares/*<share_id>*/send-email
+* Method: POST
+
+* Arguments: share_id - (int) share ID
+* POST Arguments: password - (string) the share password if enabled.
+
+Statuscodes:
+
+* 200 - successful
+* 400 - wrong or no update parameter given
+* 403 - no permission to send email on this share
+* 404 - couldn't find the share
 
 Federated Cloud Shares
 ----------------------
@@ -172,7 +232,7 @@ enabled and configured. See `Configuring Federated Cloud Sharing <https://docs.n
 .. TODO ON RELEASE: Update version number above on release
 
 Create a new Federated Cloud Share
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Creating a federated cloud share can be done via the local share endpoint, using
 (int) 6 as a shareType and the `Federated Cloud ID <https://nextcloud.com/federation/>`_
@@ -180,7 +240,7 @@ of the share recipient as shareWith. See `Create a new Share`_ for more informat
 
 
 List accepted Federated Cloud Shares
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Get all federated cloud shares the user has accepted.
 
@@ -194,7 +254,7 @@ Statuscodes:
 * 100 - successful
 
 Get information about a known Federated Cloud Share
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Get information about a given received federated cloud that was sent from a remote instance.
 
@@ -211,7 +271,7 @@ Statuscodes:
 * 404 - share doesn't exist
 
 Delete an accepted Federated Cloud Share
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Locally delete a received federated cloud share that was sent from a remote instance.
 
@@ -228,7 +288,7 @@ Statuscodes:
 * 404 - share doesn't exist
 
 List pending Federated Cloud Shares
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Get all pending federated cloud shares the user has received.
 
@@ -242,7 +302,7 @@ Statuscodes:
 * 100 - successful
 
 Accept a pending Federated Cloud Share
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Locally accept a received federated cloud share that was sent from a remote instance.
 
@@ -259,7 +319,7 @@ Statuscodes:
 * 404 - share doesn't exist
 
 Decline a pending Federated Cloud Share
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Locally decline a received federated cloud share that was sent from a remote instance.