cinder-api-microversions code

[OpenStack Infra]

https://review.openstack.org/224910
Dear bug triager. This bug was created since a commit was marked with DOCIMPACT.
Your project "openstack/cinder" is set up so that we directly report the documentation bugs against it. If this needs changing, the docimpact-group option needs to be added for the project. You can ask the OpenStack infra team (#openstack-infra on freenode) for help if you need to.

commit 6b11d276d13cc866aea9b3cfa321b3b19ee13d55
Author: scottda <email address hidden>
Date: Wed Sep 16 12:57:35 2015 +0000

    cinder-api-microversions code

    Many changes to the Cinder REST API require changes to the consumers of the API.
    For example, If we need to add a required parameter to a method that is called
     by Nova, we'd need both the Nova calling code and the cinderclient that
    Nova uses to change. But newer Cinder versions with the change must work with
    older Nova versions, and there is no mechanism for this at the moment. Adding
    microversions will solve this problem.
    With microversions, the highest supported version will be negotiated by a field
    in the HTTP header that is sent to the Cinder API. In the case where the field
    'versions' is not sent (i.e. clients and scripts that pre-date this change),
    then the lowest supported version would be used. In order to ensure that the
    API consumer is explicitly asking for a microversioned API, a new endpoint v3
    is added, which is identical to API version v2. This means that our new
    Cinder API v3 would be the default, and consumers of the API that wished to
    use a newer version could do so by using that endpoint and a microversion in
    the HTTP header.
    New tests for microversioned API features on endpoint /v3 should be added to
    cinder/tests/unit/api/v3/ directory. Existing functionality will be tested via
    the .../v2/ unit tests.

    DocImpact
    APIImpact
    Implements: https://blueprints.launchpad.net/cinder/+spec/cinder-api-microversions
    Change-Id: I48cdbbc900c2805e59ee9aebc3b1c64aed3212ae

[Michal Dulko (michal-dulko-f)]

Hey Scott, can you explain what is needed to be added to docs (maybe examples from Nova/Manila) and reassign this to openstack-manuals?

[Scott DAngelo (scott-dangelo)]

I don't think anything needs to be added that is not already included in the devref:
http://docs.openstack.org/developer/cinder/devref/api_microversion_dev.html

[Scott DAngelo (scott-dangelo)]

I'm unable to re-assign this bug to openstack-manuals (I lack the permissions).
This can be closed AFAIC, if that doesn't cause any issues.

[KATO Tomoyuki (kato-tomoyuki)]

added to http://docs.openstack.org/mitaka/config-reference/block-storage/volume-misc.html