diff --git a/api-guide/source/microversions.rst b/api-guide/source/microversions.rst index 8b31cb7574..baedcdd066 100644 --- a/api-guide/source/microversions.rst +++ b/api-guide/source/microversions.rst @@ -11,11 +11,26 @@ License for the specific language governing permissions and limitations under the License. -============== +============= Microversions -============== +============= -API v2.1 users micro versions, instead of extensions, to allow for the API -to slowly evolve over time, without breaking any existing users. +API v2.1 supports Microversions. User uses Microversions to discover the +supported API version in the cloud. If cloud is upgraded to support newer +versions, it will still support all older versions to maintain the backward +compatibility for users using older versions. Also user can discover new +features easily with Microversions, then user can take all the advantages of +current cloud. -TODO - add more information. +There are multiple cases which you can resolve with Microversions: + +Legacy v2 API user with new cloud +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The minimum version of Microversions is `2.1`, this is a version compatible +with legacy v2 API. The legacy v2 API user don't need to worry about that his +old client is broken with new cloud deployment. Cloud operator don't need to +worry that upgrading cloud to newer versions will break any user with old +client. + +TODO: add more use-cases for Microversions