Servers list in the openapi specification does not accurately reflect that the API URL may be freely chosen.

[GeraldIr]

The current servers list only specifies a singular url, namely "https://localhost/api/{version}", which indicates a schema for the server url that shouldn't be enforced, as by the description of that same server "The URL of the API MAY freely be chosen by the back-end providers".

I recommend a more open schema, or multiple schemas that cover all types of base URLs that might come up.

Here is one way he url could be structured to cover the most common cases of how openEO API urls look (e.g.: https://openeo-dev.eodc.eu/openeo/1.1.0/ or https://openeocloud.vito.be/openeo/1.1/), but more schemas can be added to cover all cases (no path_stub, no version, or combinations of the pattern) to actually represent the open nature of the naming conventions. I'm not sure if there is a way to simply introduce a wildcard value like "url": "https://*" for that to simply cover the one requirement of having https and leaving the rest open for everything.

"servers": [
      {
        "url": "https://{domain}/{path_stub}/{version}",
        "description": "The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a *recommendation* only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!",
        "variables": {
          "path_stub": {
            "default": "openeo",
            "description": "Additional path after domain that leads to the API"
          },
          "domain": {
            "default" : "localhost",
            "description" : "any server that hoststhe API"
          },
          "version": {
            "default": "v1.0",
            "description": "API versioning is RECOMMENDED. As the openEO API is following [SemVer](https://semver.org/) only the MAJOR part of the stable version numbers (i.e. versions >= 1.0.0) SHOULD be used for API versioning in the URL. The reason is that backward-incompatible changes are usually introduced by major changes. Therefore, the version number in the URL MUST not be used by the clients to detect the version number of the API. Use the version number returned from `GET /` instead."
          }
        }
      }
    ],

This is not a very urgent problem, but it does interfere with conformance checking using the openapi-core python library (and potentially cause other issues)

[m-mohr]

There are so many variants that may apply, that it seems it's not possible in the OpenAPI document to cover them all. I'll have a look, but my proposal is to simply change the document to your needs. It's anyway a good idea to have a custom OpenAPI document for your deployment that reflects the actual implementation.

[GeraldIr]

Understandable, if there is no easy way to represent the open nature of the url format in openAPI then this is a moot issue, I'm unfamiliar with the exact workings of how the url schema is deconstructed.

If the path_stub were to cover any length of additional path (e.g.: x/y/z instead of just x) I think it would be doable with just a few combinations, but if any additional forward slash needs another variable then this is indeed unfeasible. I can test this myself and come back to you on this issue.

Anyways, the priority on this is not high, I am currently editing the url in the json to my needs, I was just thinking that having it universally cover all the cases by default would have been nice!

[m-mohr]

Yeah, as far as I know a path template variable such as path_stub does not allow a slash in OpenAPI: https://github.com/OAI/OpenAPI-Specification/issues/892

[GeraldIr]

Very well, that's a shame but nothing that can be done about it if openAPI itself has no support for this.

Closed.