Clarified how clients and back-ends should implement well-known disco…

…very for `GET ./well-known/openeo` (#202)

CHANGELOG.md

@@ -35,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Service parameters and attributes in `GET /service_types` and output format parameters in `GET /file_formats` (previously `GET /output_formats`) now have a `type`, which was previously only mentioned in examples.
+- Clarified how clients and back-ends should implement well-known discovery for `GET ./well-known/openeo`. [#202](https://github.com/Open-EO/openeo-api/issues/202)
 
 ## [0.4.2] - 2019-06-11
 

openapi.json

@@ -302,7 +302,7 @@
     "/.well-known/openeo": {
       "get": {
         "summary": "Supported openEO versions",
-        "description": "Well-Known URI for openEO, listing all implemented openEO versions supported by the service provider.\nThis allows clients to easily identify the best suited openEO implementation they can use. The Well-Known URI is the entry point for clients and users, so make sure it is permanent and easy to use and remember. Please note that this URL MUST NOT be versioned as the other endpoints.\nSee [RFC 5785](https://tools.ietf.org/html/rfc5785) for more information about Well-Known URIs.",
+        "description": "Well-Known URI (see [RFC 57855](https://tools.ietf.org/html/rfc5785)) for openEO, listing all implemented openEO versions supported by the service provider.\n\nThis allows a client to easily identify the most recent openEO implementation it supports. By default, a client SHOULD connect to the most recent production-ready version it supports. Clients MAY let users choose to connect to versions that are not procution-ready versions or outdated.\n\nThe Well-Known URI is the entry point for clients and users, so make sure it is permanent and easy to use and remember. Clients MUST NOT require the well-known path (`./well-known/openeo`) in the URL that is specified by a user to connect to the back-end. A client MUST request `https://example.com/.well-known/openeo` if a user tries to connect to `https://example.com`. If the request to the well-known URI fails, the client SHOULD try to request the capabilities at `/` from `https://example.com`.\n\n**This URI MUST NOT be versioned as the other endpoints.** If your API is available at `https://example.com/api/v1.0`, the Well-Known URI SHOULD be `https://example.com`.\n\nClients MAY get additional information (e.g. title or description) about a back-end from the most recent version that has the `production` flag set to `true`.",
         "tags": [
           "Capabilities"
         ],