diff --git a/README.md b/README.md index 2de86131..9e4437d7 100644 --- a/README.md +++ b/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)). diff --git a/spec.yaml b/spec.yaml index 41a0c624..6aaaeda4 100644 --- a/spec.yaml +++ b/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