Duplicate versions in discovery

[m-mohr]

In https://openeo.vito.be/.well-known/openeo there are very similar versions listed, which seems problematic: How should a client or user know which version to use? I'm trying to figure out how to improve the situation and whether that should be improved on VITOs side, on the API side and/or on client-side. It was not meant to be this way when I specified this, but I never thought about it back then.

It seems the intention by adding the 1.0 (not 1.0.0) and 0.4 (not 0.4.2 or 0.4.0) versions was to provide something like "the latest of the minor versions", but that was meant to be handled by clients automatically so is not really needed on server-side and it seems we should enforce unique version numbers in the API.

What are your thoughts, @jdries / @soxofaan?

Also tagging @christophfriedrich as this is likely leading to strange behavior in the Hub.

By the way, the api_version should be 1.0.0-rc.2 and not 1.0.0 - there's no 1.0.0 API release (yet).

[soxofaan]

I don't completely understand why this is a problem. A user has to take some decision about version anyway at some point: use 0.4.2 or 0.4.x or 1.0.0 or 1.0.x or 1.x or 1.6.8 or 3.2.5?
The idea of the current VITO listing is indeed that a user can choose an exact API version (e.g. 0.4.2), or a more flexible one if only the major.minor part is important (e.g. 1.0).

but that was meant to be handled by clients automatically

what do you mean with that?
currently in the Python client, the user has to specify a URL like http://openeo.vgt.vito.be/openeo/0.4.1, there is no automatic resolving/forwarding going on here.

[m-mohr]

I'm speaking about this in the /.well-known/openeo docs:

By default, a client SHOULD connect to the most recent production-ready version it supports. The most recent version is determined by comparing the version numbers according to rules from Semantic Versioning, especially §11. Clients MAY let users choose to connect to versions that are not production-ready versions or outdated.

R client, JS client and Web Editor by default connect to the most recent production ready version they support. This fails if there are duplicate version numbers as then the client has to choose a random one and I guess in most implementations it will be just the first in the list.

By default the user shouldn't need to specify a version, because how should they know what they should use? In the future there's even a desire to not let users choose back-ends for some other projects in the pipeline. Then version numbers get even more distractive.
It's fine to let the users choose explicitly by setting a parameter, but the default should be easy to use without choices about version numbers they usually don't understand. Thus I don't really see the need for the major.minor versions if the Python client also follows this behavior.

currently in the Python client, the user has to specify a URL like http://openeo.vgt.vito.be/openeo/0.4.1, there is no automatic resolving/forwarding going on here.

There should be. That's what the API suggests and users in workshops asked for. The URL to be used should be http://openeo.vgt.vito.be otherwise well known discovery doesn't make much sense... All clients I'm aware of - except Python - follow this behavior.

[soxofaan]

Ok, I understand better, thanks. I guess I'm too deep in the python client to be aware of these details in other clients (and API)

Some action points I extract from this:

• Python client should support the automatic version picking based on .well-known/openeo -> Don't require users to choose an API version openeo-python-client#142
• in VITO backend we hide the 0.4.0, 0.4.1, 0.4.2, 1.0.0 variants from .well-known/openeo (but still support them) and only keep the flexible ones (0.4 and 1.0 atm) visible. I think this is how most other backends do it atm.
• in VITO backend, api_version: "1.0.0" should be api_version: "1.0.0-rc.2" for now

[m-mohr]

Yes, correct.

• in VITO backend we hide the 0.4.0, 0.4.1, 0.4.2, 1.0.0 variants from .well-known/openeo (but still support them) and only keep the flexible ones (0.4 and 1.0 atm) visible. I think this is how most other backends do it atm.

You could also list all "fixed" versions and then clients / users have more choice, I guess that's the better alternative?! 0.4 and 1.0 are aliases for latest minor version anyway, right?
Other back-ends are not comparable to your deployment as no other back-end supports multiple patch versions AFAIK, they all just update to the latest and drop previous implementations.

[m-mohr]

I'll add the following to the "well-known discovery" part of the API spec:

Any pair of API versions in this list SHOULD NOT be equal according to Semantic Versioning.

[soxofaan]

Another solution is to add a field to the well-known/openeo response, like say canonical (true by default) that can be set to false to indicated that the item is not to be handled in the automatic resolving. There should be only one canonical item for a given api_version, but backends are free to expose non-canonical ones to support certain use cases.

Without such a field we are forced to hide these from well-known/openeo (as discussed above), but it is handy to have a list of all supported versions/variants. In code we have this for example:

openeo-python-driver/openeo_driver/views.py

Lines 32 to 43 in bc8d67d

	# Available OpenEO API versions: map of URL version component to API version info
	API_VERSIONS = {
	"0.3.0": ApiVersionInfo(version="0.3.0", supported=False, advertised=False, production=False),
	"0.3.1": ApiVersionInfo(version="0.3.1", supported=False, advertised=False, production=False),
	"0.3": ApiVersionInfo(version="0.3.1", supported=False, advertised=False, production=False),
	"0.4.0": ApiVersionInfo(version="0.4.0", supported=True, advertised=True, production=True),
	"0.4.1": ApiVersionInfo(version="0.4.1", supported=True, advertised=True, production=True),
	"0.4.2": ApiVersionInfo(version="0.4.2", supported=True, advertised=True, production=True),
	"0.4": ApiVersionInfo(version="0.4.2", supported=True, advertised=True, production=True),
	"1.0.0": ApiVersionInfo(version="1.0.0", supported=True, advertised=True, production=False),
	"1.0": ApiVersionInfo(version="1.0.0", supported=True, advertised=True, production=False),
	}

[m-mohr]

May I ask why you are still maintaining the old patch-level versions? That seems quite redundant und I don't really see a good reason to do so... All the other back-ends just have once 0.3, 0.4 and 1.0. I never thought a list like yours could come up in well-known discovery, to be honest.

[m-mohr]

The issue is that well-known discovery is not versioned. Therefore I want to avoid changes as much as possible so that compatibility is ensured across versions. That's why I'm asking for good reasons above.

[soxofaan]

May I ask why you are still maintaining the old patch-level versions?

that's just a bit of legacy we will clean up. We started with patch-level versions only. I recently added support for "patch-less" url versions. And the next step is removing the patch-level versions from well-known I guess. (We still have to support them for internal use cases, however).

The issue is that well-known discovery is not versioned.

indeed that's bit of a problem for doing changes. The proposed change would be backwards compatible however.

[m-mohr]

That sounds like the issue is going away soon and no change to well-known discovery is needed?

But I'm now wondering whether there's a demand for another flag such as ignore, preferred, canonical (although I'm not quite sure what that means) or so...

[soxofaan]

That sounds like the issue is going away soon and no change to well-known discovery is needed?

indeed

[soxofaan]

already pushed a commit to only have these in well-known:

{"api_version":"0.4.2", "production":true, "url":" ..../openeo/0.4/"},
{"api_version":"1.0.0", "production":false, "url":"..../openeo/1.0/"}]}

[soxofaan]

The thing about "1.0.0-rc.2" turns out a lot harder because it trickles down through a lot of unit tests, and I currently don't see a clean way to handle it without a lot of hassle. I'm going to let it rest a bit.

[m-mohr]

The issue will be solved eventually by the new release in July. So I guess for now I'll try to relax the web editor version check...

[christophfriedrich]

Thanks for tagging me Matthias -- this wouldn't exactly make troubles for the Hub, but it wouldn't work as one might expect either.

I never thought there would be a use case for having two instances/entries of the same API version, so the Hub uses the combined well-known URL + API version as the identification of individual backend instances (so e.g. http://openeo.vgt.vito.be/ + 0.4.2). When crawling, the Hub first checks the well-known doc to see which "actual URLs" to crawl, storing them in a list that has the api_version as the key. So while building that list, when more than one entry with the same api_version exists, the newer entry overrides the older one. Only after that list is complete, the actual crawling starts. That's the reason why the Hub only displays four VITO instances at the moment despite the well-known doc listing six (and why the direct link for 0.4.2 is .../0.4 and for 1.0.0 is .../1.0 -- because the .../0.4.2 and .../1.0.0 URLs were overwritten because they are listed first).

(Interestingly, if this overriding mechanism wasn't there, the behaviour would be inverted: All URLs listed in the well-known doc would be downloaded, but only the first entry would be persisted because the database would refuse to save the later docs because they would violate the unique key.)

-> @soxofaan I appreciate the commit you made to shrink the well-known doc

-> @m-mohr I would like to change this:

Any pair of API versions in this list SHOULD NOT be equal according to Semantic Versioning.

to a "MUST NOT". Is there a compelling reason you opted for a "SHOULD NOT" only?

[m-mohr]

Not quite sure why I went for SHOULD NOT. I guess because I was still waiting for reasons here, but it seems reasonable to go for MUST NOT as most clients rely on it.

[soxofaan]

update: we did production deploy this morning and https://openeo.vito.be/.well-known/openeo now only lists:

{
  "versions": [
    {
      "api_version": "0.4.2",
      "production": true,
      "url": "https://openeo.vito.be/openeo/0.4/"
    },
    {
      "api_version": "1.0.0",
      "production": false,
      "url": "https://openeo.vito.be/openeo/1.0/"
    }
  ]
}