Fixed paths used in the discovery endpoint (#76)

* Amended the paths used in the discovery endpoint

This is to reflect how ownCloud and Nextcloud are actually using
the /ocm-provider endpoint to access a share, following further
reverse engineering.

* Improved description of share access and minor fixes

Author: glpatcern

README.md

@@ -23,16 +23,15 @@ the [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (fka Swagger) specif
 * For the core sharing functionality, the provider knows the consumer (both endpoint and user) when it creates a share with the consumer (also see [#26](https://github.com/cs3org/OCM-API/issues/26)). In addition, an optional invitation workflow is available in this specification (see below), which gives the consumer a way to automatically trust a provider (and vice versa). The [ScienceMesh](https://sciencemesh.io) infrastructure provides a managed white list of trusted federated sites.
 * Consumer doesn't have to accept a share, the resource will be available to the consumer immediately ([#25](https://github.com/cs3org/OCM-API/issues/25)).
 * Dealing with incoming shares is a vendor specific implementation. One vendor might use an 'accept before' process while another vendor might use a 'decline after' approach. This is considered part of the UX and thus not part of the interaction between different vendors. However, the consumer could notify the provider by using the introduced `/notifications` endpoint (also see [#27](https://github.com/cs3org/OCM-API/issues/27)).
-* Reverting access to outgoing shares is a vendor specific implementation. One vendor might delete an entire share while another might invalidate an access token. This is considered part of vendor specific internals and thus not part of the interaction between different vendors. However, the provider could notify the consumer by using the introduced `/notifications` endpoint (also see [#27](https://github.com/cs3org/OCM-API/issues/27)).
-* The actual file sync isn't a part of this specification. To keep this specification 'future proof', the file sync protocol will be embedded as a separate object in Open Cloud Mesh API calls. This protocol object contains all protocol specific options, e.g. WebDAV specific options.
+* Reverting access to outgoing shares is a vendor specific implementation. One vendor might delete an entire share while another might invalidate an access token. This is considered part of vendor-specific internals and thus not part of the interaction between different vendors. However, the provider could notify the consumer by using the introduced `/notifications` endpoint (also see [#27](https://github.com/cs3org/OCM-API/issues/27)).
+* The actual file sync is not part of this specification. To keep this specification 'future proof', the file sync protocol will be embedded as a separate object in Open Cloud Mesh API calls. This protocol object contains all protocol specific options, e.g. WebDAV specific options.
 
 
 ## Specification
 ### Discovery
 Authentication between services is already established. This means that this specification doesn't cover the way a service authenticates incoming API calls (e.g. through an API Key, VPN connection or IP whitelisting). In this scope we assume that the services are already authenticated.
 
-If a finite whitelist of receiver servers exists on the sender
-side, then this list may already contain all necessary endpoint details.
+If a finite whitelist of receiver servers exists on the sender side, then this list may already contain all necessary endpoint details.
 
 When a sending server allows sending to any internet-hosted receiving server, then discovery can happen from the sharee address, using the `/ocm-provider` well-known URL that receiving servers MAY provide according to this [specification](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1ocm-provider/get).
 
@@ -47,7 +46,7 @@ To access a share, the receiving server MAY use multiple ways, depending on the
 
 * If `protocol.name` = `multi`, the receiver SHOULD make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. 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://<sharedSecret>:@<host><path>`, where `<host>` is the remote server, and `<path>` is obtained by querying the [Discovery](#discovery) endpoint at the remote server and extracting the path from `resourceTypes[0].protocols.webdav`.
+* 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://<sharedSecret>:@<host><path>`, where `<host>` is the remote server, and `<path>` is obtained by querying the [Discovery](#discovery) endpoint at the remote server and getting `resourceTypes[0].protocols.webdav`.
 
 In both cases, when the share is a folder and the receiver accesses a resource within the share, it SHOULD append its relative path to that URL.
 

spec.yaml

@@ -288,29 +288,26 @@ definitions:
                 webdav:
                   type: string
                   description: |
-                    The top-level WebDAV endpoint full URI. In order to access
-                    a remote shared resource, implementations MAY use this
-                    URI as a prefix: e.g. if in a new share request's payload
-                    a `protocol.options.sharedSecret` property is defined
-                    (see singleProtocolLegacy example), implementations MAY
-                    need to append it to this URI to access the resource.
-                  example: https://my-cloud-storage.org/remote.php/dav/ocm
+                    The top-level WebDAV path at this endpoint. In order to access
+                    a remote shared resource, implementations MAY use this path
+                    as a prefix, or as the full path (see sharing examples).
+                  example: /remote.php/dav/ocm/
                 webapp:
                   type: string
                   description: |
-                    The top-level endpoint full URI for web apps. This value
+                    The top-level path for web apps at this endpoint. This value
                     is provided for documentation purposes, and it SHALL NOT
                     be intended as a prefix for share requests.
-                  example: https://my-cloud-storage.org/external/ocm
+                  example: /external/ocm/
                 datatx:
                   type: string
                   description: |
-                    The top-level endpoint full URI for data transfers. This
+                    The top-level path to be used for data transfers. This
                     value is provided for documentation purposes, and it SHALL
                     NOT be intended as a prefix. In addition, implementations
                     are expected to execute the transfer using WebDAV as
                     the wire protocol.
-                  example: https://my-cloud-storage.org/remote.php/dav/ocm
+                  example: /remote.php/dav/ocm/
       capabilities:
         type: array
         description: |