disable serving API under /v0.10 and /v0.10.0 by default?

[ltalirz]

Currently, optimade-python-tools serves the same API under three separate base urls:

• /optimade/
• /optimade/vMAJ.MIN
• /optimade/vMAJ.MIN.PAT

Besides bloating the openapi.json file and the corresponding swagger documentation, I would argue this also creates an expectation on the client side that the API will remain available under these base urls.
However - if I understand correctly - in the current implementation of the optimade-python-tools this is not foreseen. E.g. if we update the models for spec v0.10.1, then the /optimade/v0.10.0 base url will be gone.

To me this suggests that the default behavior of the server should be to serve only under /optimade, while making it easy for developers to replicate the API under additional base urls if they wish to do so.

[CasperWA]

For this, we may consider this section in the specification.

From this, it seems we can remove the version base URLs.

However, only clients are mentioned here, never really what a server SHOULD, MUST or MAY do/implement.
It was always my impression that the versions specified under the top-level meta field should be reachable with a base URL.

Concerning your example:

E.g. if we update the models for spec v0.10.1, then the /optimade/v0.10.0 base url will be gone.

This is taken care of in the spec, where it states that:

However, the client MUST NOT assume levels beyond the minor version are supported.

Personally, I like having them in this test server, to display how it may be done.

[ltalirz]

From this, it seems we can remove the version base URLs.
However, only clients are mentioned here, never really what a server SHOULD, MUST or MAY do/implement.

Hm... you are right, perhaps we should ask for clarification on this?

To be honest, section 3.1 on the base url seems over-engineered to me.

The client already has the ability to ask which versions are available and under which URLs they are served (via the available_endpoints in the info endpoint).
There is no need to specify what the client may or may not assume about the availability of versions or about the form of their base urls - the client already has all the information it needs.

As for what to do by default in optimade-python-tools I stand by my point to not introduce additional endpoints unnecessarily, but let's perhaps wait until the spec is clarified on this point.

[ltalirz]

I'll make a corresponding PR to the spec so that people can discuss this

[CasperWA]

Note: This has been updated in the spec with PR Materials-Consortia/OPTIMADE#240.

[ltalirz]

Indeed, and the new policy is: serve only under <base URL>/v0 (NOT under <base URL>)