From 4f15fbee5565d094e23ea842ab3dee9b47735930 Mon Sep 17 00:00:00 2001
From: Giuseppe Lo Presti <giuseppe.lopresti@cern.ch>
Date: Tue, 9 May 2023 16:57:15 +0200
Subject: [PATCH] Document share access

---
 README.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index bbb2f7a..2177280 100644
--- a/README.md
+++ b/README.md
@@ -10,11 +10,12 @@ the [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (fka Swagger) specif
   * [Discovery](#discovery)
   * [Share Creation](#create)
   * [Share Acceptance](#accept)
+  * [Share Access](#access)
   * [Share Deletion](#unshare)
   * [Share Updating](#update)
   * [Resharing](#reshare)
   * [Invite](#invite)
- 
+
 * [Contributing](#contributing)
 
 ## Scope and assumptions
@@ -41,6 +42,13 @@ To create a share, the sending server SHOULD make a HTTP POST request to the `/s
 ### Share Acceptance
 In response to a share creation, the receiving server MAY send back a [notification](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1notifications/post) to the sending server, with  `notificationType` set to `"SHARE_ACCEPTED"` or `"SHARE_DECLINED"`. The sending server MAY expose this information to the end user. 
 
+### Share Access
+To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property:
+
+* If `protocol.name` = `multi`, the receiver SHOULD make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote resource. If `protocol.webdav.sharedSecret` is not empty, the receiver SHOULD pass it as a `Authorization: bearer` header.
+
+* If `protocol.name` = `webdav`, the receiver SHOULD inspect the `protocol.options` property. If it contains a `sharedSecret`, as in the [legacy example](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1shares/post), then the receiver SHOULD make a HTTP PROPFIND request to `https://<token>:@<host><path>/<rel_path>`, where: `<host>` is the remote server, `<path>` is obtained by querying the [Discovery](#discovery) endpoint and extracting `resourceTypes[0].protocols.webdav`, and optionally `<rel_path>` is the relative path of the resource within the share, when needed.
+
 ### Share Deletion
 A `"SHARE_ACCEPTED"` notification followed by a `"SHARE_UNSHARED"` notification is
 equivalent to a `"SHARE_DECLINED"` notification.
@@ -73,7 +81,6 @@ The specification can be rendered as HTML documentation using [ReDoc](https://gi
 * [version 1.0](https://cs3org.github.io/OCM-API/docs.html?branch=v1.0.0&repo=OCM-API&user=cs3org#/paths/~1shares/post), current official and supported version
 * [develop branch](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org), future version supported by ScienceMesh
 
-
 The Open Cloud Mesh API specification is an open source, community-driven project. If you'd like to contribute, please follow the [Contributing Guidelines](CONTRIBUTING.md).
 
 To stage the changes of your PR, you can change the repo and branch in the URL.