=============
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: *<owncloud_base_url>/ocs/v1.php/apps/files_sharing/api/v1*

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/*<share_id>*
* 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 - (boolean) 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/*<share_id>*
* 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/*<share_id>*
* 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 - (boolean) 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 formated 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 <https://doc.owncloud.org/server/9.0/admin_manual/configuration_files/federated_cloud_sharing_configuration.html>`_.

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://owncloud.org/federation/>`_
of the share recipient as shareWith. See `Create a new Share`_ for more information.


List pending Federated Cloud Shares
-----------------------------------

Get all pending federated cloud shares the user has received.

* Syntax: /remote_shares
* Method: GET

* Result: XML with all pending federated cloud shares

Statuscodes:

* 100 - successful
* 404 - couldn't fetch shares

Accept a pending Federated Cloud Share
--------------------------------------

Locally accept a received federated cloud share that was sent from a remote instance.

* Syntax: /remote_shares/*<share_id>*
* Method: POST

* Arguments: share_id - (int) share ID

* 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/*<share_id>*
* Method: DELETE

* Arguments: share_id - (int) share ID

* Result: XML with the share information

Statuscodes:

* 100 - successful
* 404 - share doesn't exist
