Copy Offload - Client / Server API Compatibility Check

[mcfadden8]

The API to the data movement service is being exported to a c-library that may be linked in with other using executables. It would be helpful if the c-library could determine whether or not it is compatible with the service it is attempting to communicating with.

For example, if the client was originally created and compiled for a specific version of the server, and the current server is running an incompatible version, it would be best if the client could return an error code to the using program indicating the incompatibility.

Without this check, it is possible for the incompatible client to attempt to communicate with the newer server and produce unexpected behavior.

I wonder if this check could be implemented within the Connect implementation and returned as an error code there.

I had originally wrote this as an email with a specific request for a version API. However, after giving it more thought, it is really the compatibility check and error return that I am looking for as it may help with deployment concerns.

[mcfadden8]

This may be more of a documentation issue (for later, when multiple server versions are available).. But one question I have is: If I have a v3 API-complient client, is there a mechanism available to me for when I am communicating to an older (v1 or v2) server to know that I do not have the v3 capabilities?

[NateThornton]

Is your intention to fallback in the case the server is behind the client? Or would you fail any request at your layer?

What I'm wondering is if we need to support multiple versions in the Server API, or if we'd always only support the latest, and any incompatibility would require an updated server is deployed.

[mcfadden8]

If we were to have the option of falling back to the highest common denominator API version between the library and the sever, that would be the most flexible.

Supporting the most recent version on the server would require a new release of our libraries at the time of server deployment which is problematic since deployment, library release management, and statically linking applications release management are all independent functions.

[NateThornton]

In that case I'd propose a new endpoint

message IdentifyRequest {}

message IdentifyResponse {
  string version = 1;           // git hash or tag (something uniquely identifiable)
  repeated int apiVersions = 2; // array of supported API versions
}

Version would be a uniquely identifiable value that gets updated on every new server release. We will probably use simple hardcoded strings like v0.0.1-alpha until our automated release process is implemented.

API Versions would apply to all endpoints. For example, if CreateV2 is introduced with some new, incompatible format to V1, then ListV2, StatusV2, etc, would all be implemented simultaneously, even if the Request/Response parameters to those endpoints are the same as V1 implementation. Advancing the endpoints individually seems excessive - but it is possible.

I don't anticipate this happening, but API Versions is an array instead of a minimum/maximum value in case a particular API Version introduced has a defect. Like if we maintained compatibility with V1 and V2, but botched V3, and replaced it with V4. In that case, API Versions would be the list consisting of 1, 2, and 4

[mcfadden8]

This seems reasonable to me assuming we can also get a libcpp interface to obtain it.

Thanks,