Introduce a .well-known discovery endpoint and DNS SRV records

README.md

@@ -33,7 +33,12 @@ Authentication between services is already established. This means that this spe
 
 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).
+When a sending server allows sharing to any internet-hosted receiving server, then discovery can happen from the sharee address, using the `/.well-known/ocm` (or `/ocm-provider`, for backwards compatibility) URL that receiving servers SHOULD provide according to this [specification](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1.well-known~1ocm/get).
+
+To fill the gap between users knowning other peers' email addresses of the form `user@provider.org`, and the actual cloud storage endpoints being in the form `https://my-cloud-storage.provider.org`, a further discovery mechanism SHOULD be provided by implementations that wish to allow sending shares to any receiver, based on DNS `SRV` Service Records.
+
+* A provider SHOULD ensure that a `type=SRV` DNS query to `_ocm._tcp.provider.org` resolves to e.g. `service = 10 10 443 my-cloud-storage.provider.org`
+* When requested to discover the EFSS endpoint for `user@provider.org`, implementations SHOULD query the corresponding `_ocm._tcp.domain` DNS record, e.g. `_ocm._tcp.provider.org`, and subsequently make a HTTP GET request to the host returned by that DNS query, followed by the `/.well-known/ocm` URL path.
 
 ### Share Creation
 To create a share, the sending server SHOULD make a HTTP POST request to the `/shares` endpoint of the receiving server ([docs](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1shares/post)).

spec.yaml

@@ -30,15 +30,28 @@ parameters:
       the HAL navigation links (e.g. `_links.next.href`) to paginate. These
       links enable the possibility to use vendor specific pagination.
 paths:
-  /ocm-provider:
+  /.well-known/ocm:
     get:
       summary: Discovery endpoint
       description: >
-        This endpoint returns a number of properties used to discover the capabilities
-        offered by a remote cloud storage. The endpoint is named `/ocm-provider` owing
-        to already established practices and constraints with the main cloud storages
-        that implement OCM (see https://github.com/cs3org/OCM-API/pull/37#issuecomment-435875108
-        for more details).
+        Following RFC 8615, this endpoint returns the properties and capabilities
+        offered by a remote cloud storage. This endpoint is to be served as a
+        top-level URL, e.g. as in `https://my-cloud-storage.org/.well-known/ocm`.
+      responses:
+        "200":
+          description: The capabilities of this OCM service
+          schema:
+            $ref: "#/definitions/Discovery"
+  /ocm-provider:
+    get:
+      summary: Legacy discovery endpoint
+      description: >
+        This endpoint returns the properties and capabilities offered by a remote
+        cloud storage. It is a replica of `/.well-known/ocm` and it is required
+        to be supported, owing to previously established practices by the main
+        cloud storages that have implemented OCM (for more details, see
+        https://github.com/cs3org/OCM-API/pull/37#issuecomment-435875108).
+        This endpoint is to be served as a top-level URL.
       responses:
         "200":
           description: The capabilities of this OCM service