search

Open-EO / openeo-api

The openEO API specification
http://api.openeo.org
Apache License 2.0
91 stars 11 forks source link

URL Prefix uncertainties #386

Closed mmacata closed 3 years ago

mmacata commented 3 years ago

The spec tells how and when to use the URL version prefix here:

From this I understand that only / for capabilities and /.well-known/openeo need to be available without API prefix, all other endpoints must be available at /api/v1.0/ and not without version prefix. If /.well-known/openeo is not reachable, / should return the Capabilities.

Is my understanding correct? If so, I would suggest to explain this directly in the API Principles section as some important endpoints are already specified above the "Supported openEO versions" section and from e.g. Authentication it is not obvious that the prefix must to be used.

m-mohr commented 3 years ago

No, this is not entirely correct. Everything except /.well-known/openeo is recommended (this is not a requirement) to be versioned.

If you click the dropdown for the endpoint paths, you get the details for each endpoint individually, see for example:

image

image

If there are still open questions, please let me know.

m-mohr commented 3 years ago

If /.well-known/openeo is not reachable, / should return the Capabilities.

Please note that the part you are referring to here is for the clients:

If the request to the well-known URI fails, the client SHOULD try to request the capabilities at / from https://example.com.

This is just a hint at clients how to work if well-known discovery has not been implemented (fallback). That was mostly for the initial time when back-ends did not have well-known discovery. Back-ends don't necessarily need to serve anything at /.

Example: You may host your homepage at http://mundialis.de and have well known discovery at http://mundialis.de/.well-known/openeo so that clients can just use http://mundialis.de to connect as this is sometimes nicer than http://whatever-subdomain.aws.com (in case you have some kind of API on AWS). The API then could still live at http://whatever-subdomain.aws.com, but that detail would be hidden to the user.

mmacata commented 3 years ago

Ok, thanks for clarification. I never saw the small dropdown arrow icon next to the API URL field! This was the missing piece.