well-known/openeo confusion

[soxofaan]

openeo-api/openapi.yaml

Lines 883 to 886 in 16b1122

	**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 located at `https://example.com/.well-known/openeo` and the
	URI users connect to SHOULD be `https://example.com`.

While I was discussing something about .well-known/openeo with @dthiex I found this "URI MUST NOT be versioned" is a bit confusing:
is it really "forbidden" to support a not-toplevel .well-known/openeo, e.g. something like https://example.com/api/v1/.well-known/openeo or https://example.com/foobar/.well-known/openeo?
Or should it just be a recommendation: "URI SHOULD NOT be versioned" ?

[m-mohr]

https://example.com/api/v1/.well-known/openeo doesn't make a lot of sense because the intention of the well-known document to hide the versioning from the user so that the client simply can choose the best version (i.e. latest supported production usually).
It is also meant to provide a uniform URL so whenever your version changes, the user doesn't need to change the URL. So if you version it, the URL to connect to changes from the user POV and stuff may break. So yeah, of course you can relax to "SHOULD NOT", but it really is against what it is meant to be used for so I'd stick with it as it is.

[soxofaan]

I understand the goal of course, but I guess the thing that I find confusing or unclear about the current explanation is that it mixes up two aspects of .well-known URLs:

• does URL contains an API version indicator (aka "versioned")?
• does path component (directly after domain) start with .well-known/openeo ? (I understand that RFC 5785 only mentions "top level" well-known documents, but it does not forbid non-top-level ones.)

I think you can have one without the other:

• https://v1.openeo.example.com/.well-known/openeo is a versioned URL, with .well-known at top level.
• And, likewise, https://openeo.example.com/production/.well-known/openeo is not versioned, but .well-known is not at top-level.

Examples use cases that are not clear how to handle (both from client and back-end viewpoint) from the description:

• A client MUST request https://example.com/.well-known/openeo if a user tries to connect to https://example.com.

  but what should a client do when user tries to connect to https://example.com/production ? Should it first try https://example.com/.well-known/openeo or https://example.com/production/.well-known/openeo? I guess you intended the first one (because the second one is strictly speaking not a valid well-known URL), but the Python client currently will try the second one (for historic/pragmatic reasons)

• 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 located at https://example.com/.well-known/openeo and the URI users connect to SHOULD be https://example.com.

  but what if a back-end wants to host the API at a versioned domain like https://v1.example.com? You can interpret the description that the well-known should be at https://example.com/.well-known/openeo, but I think it's also possible to allow https://v1.example.com/.well-known (e.g. to point to itself, or to list sub-versions). And what if user tries to connect to https://v1.example.com: should the client be able to detect that this is a versioned URL and figure out a non-versioned well-known URL?

[m-mohr]

If you click the path in redoc (what renders our OpenAPI docs), you can see the so called "server". You can also see them in the document: https://github.com/Open-EO/openeo-api/blob/master/openapi.yaml#L523 This applies to all endpoints except ./well-known/openeo (i.e. the "API").
For the well-known document (WKD) a separate "server" is specified: https://github.com/Open-EO/openeo-api/blob/master/openapi.yaml#L895

As OpenAPI is/was(?) meant for specific APIs, you can't really fill that very well and it's also not very flexible. What is specified there are really just examples. What it is meant to say is:

• The API should be versioned, but can otherwise reside wherever you want.
• The well-known document is meant to be separate from the API, you can place it in a "nice" location so that users can connect easily (e.g. as in openEO Platform where openeo.cloud is a very nice entry point and directs to completely different URLs). As many implementations did not get that and implemented the WKD, we tried to make it clear by saying it MUST not be versioned.

Top-level for the WKD is really just what you define as your top-level, but it doesn't make sense to place it wherever versioning is in place. "production" is also some kind of versioning though. So you could also write in the API docs:

A client MUST request https://example.com/blabla/.well-known/openeo if a user tries to connect to https://example.com/blabla.

Whatever the client gets provided by the user, they must append the well-known path to that URL and connect to the newly constructed URL. That can also be in a sub-folder (but ideally it would not be). If that doesn't exist, they fall back to the given URL.

More schematically:

1. User provides a URL (may consist of protocol, host, tld, port, path) to the client
2. URL gets parsed, /.well-known/openeo is appended to the path, a request is sent to this URL
3. • On success: Read WKD, detect the best entry, and connect to that "API URL"
   • On failure: Directly connect to the given URL as if it would have been detected from the WKD as the "API URL" (that's a fallback mechanism to enforce a specific version and that's why there should not be a well-known versioned document as otherwise you can't enforce this route as it would read the WKD again)