The current state of client-server and portal-facility interactions is such that if the api is updated on one side of the interaction and the other side is not, there will potentially be a mismatch in features supported and in actions taken such that errors may be introduced into the system, or seen by the users/clients.
Within the kubernetes system, which is an api based, reconciler driven system similar to ours, the apis that are called are prefixed with a version. I think this may be a good idea for us if we are going to change under-the-hood or other back-end workflows, because it would allow an old client to make a call to a deprecated api url and get a response based on its own version.
An example might be:
- api endpoint running v1.1.16
client calls:
http|grpc://endpoint-addres/v1.1.15/createuser
example responses:
- unmaintained/too old/too new:
"error: unknown client version v1.1.15" - deprecation (incompatibility):
"error: create user v1.1.15 is deprecated, update your client" - eventual deprecation (versions compatible, but skewed):
"warning: create user v1.1.15 successful, server is v1.1.16, update your client" - success (compatible):
"create user v1.1.15 successful (server is v1.1.16)"
Ideally a client that is version compatible with the api server will have no need to maintain an external compatibility matrix, since any response to the client would contain the client and server version, and the returned message could be ignored by the client or parsed out on a verbosity upgrade. This also would place versions of the extant clients (whether they are internal consumers like portal<–>facility or external like mrg<–>portal) into the apiserver logs which could also be used to populate a metric merge_client_calls{version="",source=""} or something
this is just my naive take on a workable solution for version skews between api driven clients and servers as an opening for a discussion. a more serious RFC/RFP can happen later as this work is not yet urgent.