JSON API reporting hledger-web's version

[real-dam]

Hi,

It appears the JSON API of hledger-web has changed between version 1.14 and 1.15.1.

The difference I am facing when submitting transactions via PUT /transactions is that the aprice element of the amount (transaction→tpostings→pamount→aprice) should be null in 1.15.1 and an object { "tag": "NoPrice" } in 1.14.

While having a stable version of the API at e.g. /api/1/transactions would be easiest for me as a consumer, I imagine it would be quite hard to provide, possibly requiring cloning the whole API on every change and writing numerous tests to ensure it doesn't change unexpectedly.

Instead, I'd like to request a new API that reports the version of hledger-web. This way all the multi-version handling is left to the consumer.

Something like GET /version returning { "major": 1, "minor": 15, "patch": 2 } would be great.

If one day there is a stable API, that could be extended with "api": 42.

Thank you for considering.

[simonmichael]

Thanks for the report. How about /version returning a simple natural number ? 1, 2..

[real-dam]

Sure. An increasing natural number would work too.

I just imagined it would be easier to refer to a version string that is already available somewhere.

[simonmichael]

Maybe both /api-version (or /version - natural number) and /hledger-version (hledger-web version string).

[real-dam]

(In case you still need me to comment on this)
What would the semantics of /api-version be? Increased with every release or increased only on incompatible changes?

'Incompatible' would mean changing a member between string/number/object/list like what happened in f6fa76b leading to #1360. Removal of members is probably incompatible too. Adding new ones is fine. (for the parser in MoLe, that is)

Ideally, I'd prefer /api-version that is changed when incompatible changes are made, and /hledger-version for display/crash reporting purposes. If that is too much work, a simple /hledger-version would still be great.

[simonmichael]

Thanks for the ping. As a first step I have added /version which is just the hledger version string, same as hledger-web --version. Next step is perhaps a test so we know when the JSON API changes, cf #1360 (comment)

[simonmichael]

PS: the hledger version string is 2 or more dot-separated numbers. We follow a simplified form of https://pvp.haskell.org:

MA.JOR[.MINOR]

A change in features, API, JSON, file formats etc. means (should mean) a change to MA.JOR, which normally happens at the start of each quarter.
Bugfixes and small compatible changes are released with a change to MINOR, whenever needed.

[Xitian9]

Has this issue been resolved to your satisfaction? Can we close this?