Provide an endpoint to query versions of core and loaded packages

[Morendil]

Consider a developer running a service against a local instance of OpenFisca (for instance because they want to minimize the network path, or because they've enabled a computationally expensive reform) wanting to quickly know whether upgrading to the latest version breaks anything.

They might connect their service to api.openfisca.fr for testing purposes, and decide to upgrade if nothing seems to break (and their CI tests pass, etc.). But at present there doesn't seem to be a way to know what versions are running on api.openfisca.fr and thus to know just what it is safe to upgrade to.

The API itself returns a version number but that is very coarse-grained; the X-API-Version header returns the version number of this repository, but that doesn't seem quite reliable as a way of knowing the exact versions of the underlying core, packages and reforms.

A /version endpoint returning the version numbers of openfisca-core and any packages loaded into OpenFisca (country, extensions, maybe even enabled reforms) would be valuable in this and possibly other scenarios. Alternately, if I've missed an existing way to check this, I'd love to learn of it!

[MattiSG]

Thanks for the feedback @Morendil!

You currently can get the information regarding api.openfisca.fr through https://legislation.openfisca.fr: the metadata source under the logo is the same as for the API.

The latest version of the API (currently available on api-test.openfisca.fr) exposes the Country-Package and Country-Package-Version information through headers, which you can see on its interactive documentation (unfold any of the endpoints).

As you have noticed, the current (soon “legacy”) version of the API exposes a X-API-Version header which exposes the deployed version of the API package.

In order to improve the situation in the future, would you please be so kind to tell us if the country package identifier and version are enough, or if your request to know the Core and reforms still stands? Also, would you prefer to find this information through headers or through an endpoint? Finally, if you did have an endpoint, would you still use the headers?

Thanks for your inputs, and please let us know if the suggested workarounds work for you! :)

[Morendil]

@MattiSG Getting the version from legislation.openfisca.fr is a good idea too, I might have thought of that. But querying the API itself for that info strikes me as better in many respects - reliable, documented, reassuring.

When testing complex systems I quite often end up looking for (and often adding) a way to dynamically query the running system for a version identifier for the main component and any dependencies that are built separately, often to the granularity of build number or commit name. As a developer I'm usually happy when bug reports contain that info ! And it's a time saver for those occasions where you're not sure your continuous deployment script is actually continuous.

Knowing the country package version is a good start though; as @Anna-Livia remarked IRL when we discussed this, the country package declares its dependencies, so the core version can be known. This is perhaps enough for practical purposes and for the time being.

I'll close this as being addressed by the upcoming version, through X-API-Version, and the workaround; if the need comes up again in development I'll invest some time in a PR for richer version info.