This issue is an attempt to collect and organize different topics related to microversions which have been taking place in other PRs and Issues.

This issue is to discuss high-level implementation decisions, not about how the decision will actually be implemented. Please refrain from discussing the performance benefit of strings.Contains vs regexp.MatchString or how a specific implementation saves n additional function calls.

Background Docs:

• https://developer.openstack.org/api-guide/compute/microversions.html
• http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html
• https://github.com/openstack/keystoneauth/blob/master/doc/source/using-sessions.rst

External examples:

• https://github.com/openstack/python-novaclient/blob/2e307bb3e8c92c68e4de7829df60055e9b573c40/novaclient/v2/hypervisors.py
• https://github.com/openstack/python-novaclient/blob/2e307bb3e8c92c68e4de7829df60055e9b573c40/novaclient/api_versions.py
• https://github.com/openstack/python-manilaclient/blob/c8bb1a275587e4aafde9850e3133b71f75c0e53b/manilaclient/v2/share_replicas.py
• https://github.com/openstack/python-cinderclient/blob/ce2c1daee5bef64b5c932f4e0ee787694a6309f4/cinderclient/v3/messages.py

Microversion Logs:

• https://docs.openstack.org/nova/latest/reference/api-microversion-history.html
• https://github.com/openstack/cinder/blob/master/cinder/api/openstack/rest_api_version_history.rst
• https://github.com/openstack/manila/blob/master/manila/api/openstack/rest_api_version_history.rst

Topics raised so far:

• To what extent does Gophercloud need to be concerned about microversions?

Using the above hypervisors.py link as an example, if Gophercloud were to match functionality, then microversions will play a significant role. The above link is useful for illustrative purposes because the file is small yet several microversion-specific features are used:

• "guarding" API calls with a min and max microversion
• Altering functionality in the midst of an API call based on the microversion.

In addition, an example has been cited which shows additional Fields being added in new microversions. This may have an effect on Gophercloud's result structures.

But why is there so much microversion logic in the client?

• How will API versions be retrievable via Gophercloud?

Decision: Each service will have a versionless apiversions package.

• How will Gophercloud send a microversion to the API service?

Decision: Support for sending the service-specific version header was added in 5acaa3c.

• What microversion information should the ServiceClient hold?

The ServiceClient currently supports setting and retrieving a single microversion value at client.Microversion.

A question of whether the ServiceClient should also store minimum and maximum microversion of the API service has been raised. python-novaclient only seems to be concerned about a single value: the microversion set in the client. That's a good precedence to go off of, but I'll leave this item open for discussion.

• Should Gophercloud automatically populate the ServiceClient with a requested microversion, the API service's minimum supported microversion, or nothing at all?

Please see the points made in the spec under "Clients should expect the following behavior from the server".

My interpretation of the above points is that the API service should be quite lenient toward the client not specifying a microversion at all. Problems may arise when the API service has not implemented functionality to make those points work. The client may then see unexpected behavior.

• Should Gophercloud prevent a client from calling a method if client.Microversion is incompatible?

I might be incorrect about this, but it seems as though the only reason for doing this is to provide the user with an error that the API service itself has chosen not to respond with. According to the spec, if the client was allowed to make any API call, the service would respond with a clear error the client's currently set microversion is not compatible as well as which microversion(s) are compatible.

Referring to a statement earlier ("But why is there so much microversion logic in the client?"), having the client handle a large amount of microversion functionality might be to provide a better end-user experience when the API service has chosen to use microversions, but has not implemented the correct 406 response.

Given that I've found examples of preventing/guarding in three different Python clients, either this is standard practice or there's another reason for limiting so many calls with the compatible microversions that I'm not aware of yet.

• Should Gophercloud alter result struct fields based on the microversion?

I think this just made #300 even more difficult.

• Should Gophercloud alter behavior of an API call depending on the microversion?

There's already precedence of Gophercloud implementing extra logic in building some API calls. Altering behavior based on microversion seems no different.