API endpoint for querying server version

[janusw]

Minor feature request: It would be nice to have a way to query the server version via the API. AFAICS this is not possible right now, or is it?

One could either add a new endpoint (/version?), which simply returns something like:

{
    "version": "1.5.1"
}

Alternatively, one could also include it into the /health endpoint, so that it returns:

{
    "status": "OK",
    "version": "1.5.1"
}

(I'd slightly prefer the second option here.)

For the version string, I can also see two different options:

• Either just use the content of the VERSION file (e.g. 1.5.0 or 1.5.1).
• Or use the output of git describe --tags --always. For current master this yields v1.5.1-2-gde6948d, but for the current dev branch it just gives the git hash e72a26c.

The second variant really gives a unique version string for every commit, while the first one is more straightforward (but may not be unique, or at least less exact). Both would be an improvement over the status quo. One could also imagine outputting both of them in different json fields.

[ajnisbet]

What is your use case for this? The public API is kept on the latest version, and if you're hosting the API yourself you should know the version yeah?

There is some precident for returning the version as part of the health check: https://tools.ietf.org/id/draft-inadarei-api-health-check-05.html, I'd also consider a response header.

[janusw]

What is your use case for this?

Well, mostly just informational purposes for now. Like: Checking if different (private or public) servers run on the same version etc.

Later this could also be helpful in dealing with changes of API or behavior in the client, e.g.

if (major_version < 2)
  use_this_query()
else
  use_the_other_one()

etc

Note that I don't actually have that problem yet, but a hook for querying the version should be introduced before that comes up for anyone ;)

The public API is kept on the latest version, and if you're hosting the API yourself you should know the version yeah?

Yeah, I do have other means of checking the version of my self-hosted server, but my users don't.

There is some precident for returning the version as part of the health check: https://tools.ietf.org/id/draft-inadarei-api-health-check-05.html

Absolutely.

I'd also consider a response header.

Also possible, but for my taste a health-check field would be preferable.

Btw, another useful addition for the /health endpoint might be to list the available datasets (which, apart from the version, can be another major difference in how different instances of OTD behave).

[janusw]

For the version string, I can also see two different options:

* Either just use the content of the `VERSION` file (e.g. `1.5.0` or `1.5.1`).

* Or use the output of `git describe --tags --always`. For current master this yields `v1.5.1-2-gde6948d`, but for the current dev branch it just gives the git hash `e72a26c`.

Btw, in case you'd consider the second variant: How about putting the dev branch on top of the last release tag (from now on), instead of branching off the the release commit? Such a layout would make git describe give more meaningful output on the dev branch (including last tag and number of releases since then).

[ajnisbet]

The api now adds a x-opentopodata-version header to every response. This keeps the healthcheck endpoint clean, and makes it easier to debug requests to other endpoints.

How about putting the dev branch on top of the last release tag

I basically use git-flow for this project, which has a long-lived dev branch. I think yours is a good idea, but it's a bit beyond my git skills and I like sticking to a standard approach for open projects.

Similarly, having the git commit in the version string would be helpful, but adds a dependency in the api to git. Also the public api runs in a different repo for various hacky ops reasons, so the commit ids wouldn't match up.

[janusw]

The api now adds a x-opentopodata-version header to every response. This keeps the healthcheck endpoint clean, and makes it easier to debug requests to other endpoints.

Cool :D Thanks a bunch for looking into it! 👍

How about putting the dev branch on top of the last release tag

I basically use git-flow for this project, which has a long-lived dev branch. I think yours is a good idea, but it's a bit beyond my git skills and I like sticking to a standard approach for open projects.

Yeah, I know that one, and it's perfectly reasonable IMHO, except for the fact that it completely breaks git describe, because all the release tags live on a separate master branch (and are usually not visible on the develop or release branches). I never understood that part, to be honest. Why not have the tags directly on the release branches? You could still have a master branch that is always updated to the latest release ...

Similarly, having the git commit in the version string would be helpful, but adds a dependency in the api to git. Also the public api runs in a different repo for various hacky ops reasons, so the commit ids wouldn't match up.

Sure, no problem. What you implemented now is perfectly reasonable. I was merely trying to point out some of the possible options for this kind of feature 😄