add /server-info end point providing machine-readable information

[yarikoptic]

ATM in dandi-cli I need to

• hardcode mapping for deployments (local, main) for corresponding addresses of underlying girder service
• embed similar mapping for netlify instances which uses main girder instance
• support a cacophony of url mappings for downloader support (this hopefully would be gone when we get our API going)

I think it would be nice if server could be queried relevant information. I see following (assuming json, with non-json comments ;-)) structure could be returned now

{
  "version": 1,  # version of this spec
  "api-versions": [],  # Later 1, 2 and much later 2, 3, 4
  "cli-minimal-version": "0.6.0",
  "cli-bad-versions": [],  # 
  "services": {
      "girder": {
          "url": "https://girder.dandiarchive.org"
       },
       "webui": {
          "url": "https://gui.dandiarchive.org"
       },
       "api": {
           "url": "https://publish.dandiarchive.org/api"
       },
       "jupyterhub": {
          "url": "https://hub.dandiarchive.org"
       }
}

Then any specific deployment could provide its own details, so clients could avoid any hardcoding, work with any deployment, and provide user with an informative error if they encounter some version they do not support, or a deployment lacking a specific feature/service.

May be there is a better, standardized schema for such descriptions already which we could adopt.

[yarikoptic]

At least until API (and thus version) is formalized and used by both dandiarchive and dandi-cli, we might also want to include in the server record some "comprehension" of the urls which currently lives in dandi-cli: https://github.com/dandi/dandi-cli/blob/master/dandi/download.py#L17
which maps urls to dandisets, folders and items.

[mgrauer]

Yes I agree. Can we include this as part of the API chat?

[yarikoptic]

I have moved this issue from the webui dandiarchive repository. ATM, although web ui does have that information hardcoded, so does dandi-cli etc. So we better centralize it ATM in the simplest and most "central" component, which is the redirector.

From the original description I will remove version since it was pertinent specifically to dandiarchive component.

If entry level domain dandiarchive.org provides /server-info then any client (web ui or dandi-cli) could use it to discover services to talk to. The same could be applied to "localhost" etc, thus avoiding hardcoding anything in the code.

[yarikoptic]

@jwodder . I wonder if we could just use setuptools/packaging format for "cli-versions" : ">=0.6, !=0.6.2, <0.9.0" and check if known version satisfies the requirement.

[jwodder]

@yarikoptic You're asking whether the server could specify allowed client versions and have the client check that its version matches? Yes, that's doable using packaging; see the section on specifier sets. However, keep in mind that this tightly couples the API to a specific client implementation, which isn't good for the long-term health of an API. A better idea would be for the server to specify the version of the API that it uses and for the client to check whether it supports that version.

[yarikoptic]

@satra also suggested that we could use some dedicated OPTIONS call (instead of GET) to request such information from the server. I personally have no preference to either explicit PATH and GET or OPTIONS on /.

[jwodder]

@yarikoptic What, if anything, should the endpoint currently return for the keys other than "services"?

[yarikoptic]

ATM, (and I removing api-versions since pertinent only to "api" service, and afaik it is shy to announce any version ATM anyways) something like this:

  "version": "1.0.0",
  "cli-minimal-version": "0.5.0",
  "cli-bad-versions": [],

client would make use of versions information, and could also ensure that version is within 1.x series as the one it would support ATM. And if not (after a check for cli-minimal-version since that might be more informative ATM) -- raise an exception.

Then we could add more fields as needed and progress "version" forward while maintaining compatibility with this basic info "interface".