Create a method to query which version of LCF an endpoint implements

[anthonywhitford]

A terminal client can be provided as a SaaS web solution, enabling the terminal client vendor to provide services hosted from a single location and benefit from the economies of scale. This presents an issue, that each library customer could be operating a different implementation version of LCF, however, there is no current mechanism to positively request and respond to the question of "Which version of LCF are you running?"

Can we implement a simple URI / Entity to enable an electronic system to proactively request the implementation version number from an LCF deployment?

eg.

Request GET /lcf {with no other components}

Response HTTP/200 - OK

1.3.5

[anthonywhitford]

In considering this, I think there are two items we should resolve:

1. As with all other LCF services, we should support the explicit request for a version number, with both the request and response complying with a described and machine-readable structure. This would mean implementing a specific "/version" service with a prescribed response.
2. Since callers can request the explicit version number, the presence of the /1.0/ within all LCF v 1.x URI paths becomes redundant. This should therefore be removed. This would also align with the earlier policy decision to leave /1.0/ unchanged for anything other than breaking API changes, meaning it does not accurately reflect the version of the running service.

Recommended changes are therefore: A. Remove the mandate for the /1.0/ within LCF URI paths. eg. /lcf/1.0/patron/1234 becomes /lcf/patron/1234. B. Implement /lcf/version to enable clients to request the version of the running LCF service. C. The response header lcf-version should be removed (R00D07 from the REST Web Services implementation) D. The response to /lcf/version should comply with the following entity definition:

E16 LCF VERSION

Description

The VERSION entity enables LCF implementations to respond, answering the question "Which LCF version are you?"

Properties

Id	Element	SIP2 ID	Card.	Format	Description
E16D01	version		1	String	LCF version string, compliant with semantic version model. Aligned with the original R00D07 defintion.
E16D02	build-date		0-1	DateTime		(Optional) build date for this vendor version.

e.g.

<lcf-version>
<version>1.3.1</version>
<build-date>2024-01-01 13:59:25</date>
</lcf-version>

[franciscave]

This sounds logical to me, but I'm wondering how this could be implemented in a backwards-compatible way. Any existing implementation won't support the new entity E16. Presumably, if the "which LCF version are you?" GET request is made to an existing implementation, the HTTP response will be an exception of some kind or a '404', in which case the client will know to fall back on the current request style (including '1.0' in the request URI path). If the request is successful and the version number is returned, the client can continue using the new request style.

[anthonywhitford]

Yes, that's right. Given the Use Case, where a terminal application is communicating with multiple LCF endpoints, the terminal application will require code to handle each version of LCF as they are implemented over time. ie, Customer A running LCF 1.2.0, and Customer B running LCF 1.3.0. The client therefore needs the mechanism to determine which version of LCF it is communicating with and update the URIs it will invoke for each version of LCF it supports.

With this proposal, GET /lcf/version will respond with an exception as E16 is not known in LCF 1.3.x. The terminal application handles this exception response as "The LCF version running pre-dates the existence of E16", which means LCF version 1.3.x or earlier. The terminal client uses this information to revert to the current URI scheme for v1.3.x, where the /1.0/ is present within the URIs.

This means the change is a breaking change to the LCF definition, however it can be seamlessly handled by terminal applications.

We could add a page describing a recommended implementation pattern to permit transitions of LCF versions. Would that be helpful?

[franciscave]

I'm slightly in two minds as to whether this is a breaking change across the whole of LCF or just in the REST web service specification. But, on reflection, it is probably cleaner to make it a breaking change across the board, so that we can fix the version number in entity E16 for each released version of LCF in both the Data Framework and the entity XML binding.

[anthonywhitford]

As an example, here's a schematic of how the client can handle changing LCF versions with minimal impact.

In this model, the client only needs to update the respective "client" class with any changes, inheriting previous behaviour from earlier versions through inheritance (extension) of the previous client implementation.

I agree about resolving the version numbering issues cleanly. If we don't we are only storing technical debt for the future.