github.com/gophercloud/gophercloud@v1.11.0/docs/MICROVERSIONS.md (about)

     1  # Microversions
     2  
     3  ## Table of Contents
     4  
     5  * [Introduction](#introduction)
     6  * [Client Configuration](#client-configuration)
     7  * [Gophercloud Developer Information](#gophercloud-developer-information)
     8  * [Application Developer Information](#application-developer-information)
     9  
    10  ## Introduction
    11  
    12  Microversions are an OpenStack API ability which allows developers to add and
    13  remove features while still retaining backwards compatibility for all prior
    14  versions of the API.
    15  
    16  More information can be found here:
    17  
    18  > Note: these links are not an exhaustive reference for microversions.
    19  
    20  * http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html
    21  * https://developer.openstack.org/api-guide/compute/microversions.html
    22  * https://github.com/openstack/keystoneauth/blob/master/doc/source/using-sessions.rst
    23  
    24  ## Client Configuration
    25  
    26  You can set a specific microversion on a Service Client by doing the following:
    27  
    28  ```go
    29  client, err := openstack.NewComputeV2(providerClient, nil)
    30  client.Microversion = "2.52"
    31  ```
    32  
    33  ## Gophercloud Developer Information
    34  
    35  Microversions change several aspects about API interaction.
    36  
    37  ### Existing Fields, New Values
    38  
    39  This is when an existing field behaves like an "enum" and a new valid value
    40  is possible by setting the client's microversion to a specific version.
    41  
    42  An example of this can be seen with Nova/Compute's Server Group `policy` field
    43  and the introduction of the [`soft-affinity`](https://developer.openstack.org/api-ref/compute/?expanded=create-server-group-detail#create-server-group)
    44  value.
    45  
    46  Unless Gophercloud is limiting the valid values that are passed to the
    47  Nova/Compute service, no changes are required in Gophercloud.
    48  
    49  ### New Request Fields
    50  
    51  This is when a microversion enables a new field to be used in an API request.
    52  When implementing this kind of change, it is imperative that the field has
    53  the `omitempty` attribute set. If `omitempty` is not set, then the field will
    54  be used for _all_ microversions and possibly cause an error from the API
    55  service. You may need to use a pointer field in order for this to work.
    56  
    57  When adding a new field, please make sure to include a GoDoc comment about
    58  what microversions the field is valid for.
    59  
    60  Please see [here](https://github.com/gophercloud/gophercloud/blob/917735ee91e24fe1493e57869c3b42ee89bc95d8/openstack/compute/v2/servers/requests.go#L215-L217) for an example.
    61  
    62  ### New Response Fields
    63  
    64  This is when a microversion includes new fields in the API response. The
    65  correct way of implementing this in Gophercloud is to add the field to the
    66  resource's "result" struct (in the `results.go` file) as a *pointer*. This
    67  way, the developer can check for a `nil` value to see if the field was set
    68  from a microversioned result.
    69  
    70  When adding a new field, please make sure to include a GoDoc comment about
    71  what microversions the field is valid for.
    72  
    73  Please see [here](https://github.com/gophercloud/gophercloud/blob/ed4deec00ff1d4d4c8a762af0c6360d4184a4bf4/openstack/compute/v2/servers/results.go#L221-L223) for an example.
    74  
    75  ### Modified Response Fields
    76  
    77  This is when the new type of the returned field is incompatible with the
    78  original type. When this happens, an entire new result struct must be
    79  created with new Extract methods to account for both the original result
    80  struct and new result struct.
    81  
    82  These new structs and methods need to be defined in a new `microversions.go`
    83  file.
    84  
    85  Please see [here](https://github.com/gophercloud/gophercloud/blob/917735ee91e24fe1493e57869c3b42ee89bc95d8/openstack/container/v1/capsules/microversions.go) for an example.
    86  
    87  ## Application Developer Information
    88  
    89  Gophercloud does not perform any validation checks on the API request to make
    90  sure it is valid for a specific microversion. It is up to you to ensure that
    91  the API request is using the correct fields and functions for the microversion.