Closed soxofaan closed 1 year ago
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.
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:
.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. 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 tohttps://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?
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:
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 tohttps://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:
/.well-known/openeo
is appended to the path, a request is sent to this URL
https://github.com/Open-EO/openeo-api/blob/16b1122c7090cc4fedcabace48686a4f73c1c876/openapi.yaml#L883-L886
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 likehttps://example.com/api/v1/.well-known/openeo
orhttps://example.com/foobar/.well-known/openeo
? Or should it just be a recommendation: "URI SHOULD NOT be versioned" ?