============= OCS Share API ============= The OCS Share API allows you to access the sharing API from outside over pre-defined OCS calls. The base URL for all calls to the share API is: */ocs/v2.php/apps/files_sharing/api/v1* All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``. Local Shares ------------ Get all Shares ^^^^^^^^^^^^^^ Get all shares from the user. * Syntax: /shares * Method: GET * Result: XML with all shares Statuscodes: * 100 - successful * 404 - couldn't fetch shares Get Shares from a specific file or folder ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Get all shares from a given file/folder. * Syntax: /shares * Method: GET * URL Arguments: path - (string) path to file/folder * URL Arguments: reshares - (boolean) returns not only the shares from the current user but all shares from the given file. * URL Arguments: subfiles - (boolean) returns all shares within a folder, given that *path* defines a folder * Mandatory fields: path * Result: XML with the shares Statuscodes: * 100 - successful * 400 - not a directory (if the 'subfile' argument was used) * 404 - file doesn't exist Get information about a known Share ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Get information about a given share. * Syntax: /shares/** * Method: GET * Arguments: share_id - (int) share ID * Result: XML with the share information Statuscodes: * 100 - successful * 404 - share doesn't exist Create a new Share ^^^^^^^^^^^^^^^^^^ Share a file/folder with a user/group or as public link. * Syntax: /shares * Method: POST * POST Arguments: path - (string) path to the file/folder which should be shared * POST Arguments: shareType - (int) 0 = user; 1 = group; 3 = public link; 6 = federated cloud share * POST Arguments: shareWith - (string) user / group id with which the file should be shared * POST Arguments: publicUpload - (string) allow public upload to a public shared folder (true/false) * POST Arguments: password - (string) password to protect public link Share with * POST Arguments: permissions - (int) 1 = read; 2 = update; 4 = create; 8 = delete; 16 = share; 31 = all (default: 31, for public shares: 1) * Mandatory fields: shareType, path and shareWith for shareType 0 or 1. * Result: XML containing the share ID (int) of the newly created share Statuscodes: * 100 - successful * 400 - unknown share type * 403 - public upload was disabled by the admin * 404 - file couldn't be shared Delete Share ^^^^^^^^^^^^ Remove the given share. * Syntax: /shares/** * Method: DELETE * Arguments: share_id - (int) share ID Statuscodes: * 100 - successful * 404 - file couldn't be deleted Update Share ^^^^^^^^^^^^ Update a given share. Only one value can be updated per request. * Syntax: /shares/** * Method: PUT * Arguments: share_id - (int) share ID * PUT Arguments: permissions - (int) update permissions (see "Create share" above) * PUT Arguments: password - (string) updated password for public link Share * PUT Arguments: publicUpload - (string) enable (true) /disable (false) public upload for public shares. * PUT Arguments: expireDate - (string) set a expire date for public link shares. This argument expects a well formatted date string, e.g. 'YYYY-MM-DD' .. note:: Only one of the update parameters can be specified at once. Statuscodes: * 100 - successful * 400 - wrong or no update parameter given * 403 - public upload disabled by the admin * 404 - couldn't update share Federated Cloud Shares ---------------------- Both the sending and the receiving instance need to have federated cloud sharing enabled and configured. See `Configuring Federated Cloud Sharing `_. .. 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 `_ of the share recipient as shareWith. See `Create a new Share`_ for more information. List accepted Federated Cloud Shares ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Get all federated cloud shares the user has accepted. * Syntax: /remote_shares * Method: GET * Result: XML with all accepted federated cloud shares 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. * Syntax: /remote_shares/** * Method: GET * Arguments: share_id - (int) share ID as listed in the id field in the ``remote_shares`` list * Result: XML with the share information Statuscodes: * 100 - successful * 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. * Syntax: /remote_shares/** * Method: DELETE * Arguments: share_id - (int) share ID as listed in the id field in the ``remote_shares`` list * Result: XML with the share information Statuscodes: * 100 - successful * 404 - share doesn't exist List pending Federated Cloud Shares ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Get all pending federated cloud shares the user has received. * Syntax: /remote_shares/pending * Method: GET * Result: XML with all pending federated cloud shares Statuscodes: * 100 - successful Accept a pending Federated Cloud Share ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Locally accept a received federated cloud share that was sent from a remote instance. * Syntax: /remote_shares/pending/** * Method: POST * Arguments: share_id - (int) share ID as listed in the id field in the ``remote_shares/pending`` list * Result: XML with the share information Statuscodes: * 100 - successful * 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. * Syntax: /remote_shares/pending/** * Method: DELETE * Arguments: share_id - (int) share ID as listed in the id field in the ``remote_shares/pending`` list * Result: XML with the share information Statuscodes: * 100 - successful * 404 - share doesn't exist