Merge "[doc][api-ref] Fix annotation and missing parameters"

api-ref/source/parameters.yaml

@@ -415,6 +415,7 @@ share_type_query:
   in: query
   required: false
   type: string
+  min_version: 2.23
 share_types_query:
   description: |
     A list of one or more share type IDs. Allows filtering share groups.
@@ -2861,6 +2862,14 @@ share_id_2:
   in: body
   required: true
   type: string
+share_instance_cast_rules_to_readonly:
+  description: |
+    If the share instance has its ``cast_rules_to_readonly`` attribute set to
+    True, all existing access rules will be cast to read/only.
+  in: body
+  required: true
+  type: string
+  min_version: 2.30
 share_instance_id_1:
   description: |
     The UUID of the share instance.
@@ -3020,11 +3029,12 @@ share_replica_az:
   type: string
 share_replica_cast_rules_to_readonly:
   description: |
-    Since the share instance has its ``cast_rules_to_readonly`` attribute
+    If the share replica has its ``cast_rules_to_readonly`` attribute set to
-    set to True, existing rules will be cast to read/only.
+    True, all existing access rules will be cast to read/only.
   in: body
   required: true
   type: string
+  min_version: 2.30
 share_replica_created_at:
   description: |
     The date and time stamp when the share replica was created.

api-ref/source/quota-sets.inc

@@ -130,11 +130,13 @@ Response example
    :language: javascript
 
 
-Show quota set in detail
+Show quota set in detail (since API v2.25)
-========================
+==========================================
 
 .. rest_method::  GET /v2/{tenant_id}/quota-sets/{tenant_id}/detail?user_id={user_id}
 
+.. versionadded:: 2.25
+
 Shows quotas for a tenant in detail.
 
 If you specify the optional ``user_id`` query parameter, you get

api-ref/source/samples/share-instances-list-response.json

@@ -6,11 +6,8 @@
             "availability_zone": "nova",
             "replica_state": null,
             "created_at": "2015-09-07T08:41:20.000000",
-            "export_location": "10.254.0.3:/shares/share-081f7030-c54f-42f5-98ee-93a37393e0f2",
             "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
-            "export_locations": [
+            "cast_rules_to_readonly": false,
-                "10.254.0.3:/shares/share-081f7030-c54f-42f5-98ee-93a37393e0f2"
-            ],
             "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
             "host": "manila2@generic1#GENERIC1",
             "id": "081f7030-c54f-42f5-98ee-93a37393e0f2"
@@ -21,11 +18,8 @@
             "availability_zone": "nova",
             "replica_state": null,
             "created_at": "2015-09-07T08:51:34.000000",
-            "export_location": "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b",
             "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
-            "export_locations": [
+            "cast_rules_to_readonly": false,
-                "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b"
-            ],
             "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
             "host": "manila2@generic1#GENERIC1",
             "id": "75559a8b-c90c-42a7-bda2-edbe86acfb7b"

api-ref/source/samples/share-show-instance-response.json

@@ -5,11 +5,8 @@
         "availability_zone": "nova",
         "replica_state": null,
         "created_at": "2015-09-07T08:51:34.000000",
-        "export_location": "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b",
+        "cast_rules_to_readonly": false,
         "share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
-        "export_locations": [
-            "10.254.0.3:/shares/share-75559a8b-c90c-42a7-bda2-edbe86acfb7b"
-        ],
         "share_server_id": "ba11930a-bf1a-4aa7-bae4-a8dfbaa3cc73",
         "host": "manila2@generic1#GENERIC1",
         "access_rules_status": "active",

api-ref/source/share-access-rule-metadata.inc

@@ -1,7 +1,7 @@
 .. -*- rst -*-
 
 ============================================
-Share access rule metadata (Since API v2.45)
+Share access rule metadata (since API v2.45)
 ============================================
 
 Updates, and unsets share access rule metadata.
@@ -11,6 +11,8 @@ Update share access rule metadata
 
 .. rest_method::  PUT /v2/{tenant_id}/share-access-rules/{access_id}/metadata
 
+.. versionadded:: 2.45
+
 Updates the metadata for a share access rule.
 
 Response codes
@@ -61,6 +63,8 @@ Unset share access rule metadata
 
 .. rest_method::  DELETE /v2/{tenant_id}/share-access-rules/{access_id}/metadata/{key}
 
+.. versionadded:: 2.45
+
 Un-sets the metadata on a share access rule.
 
 To unset a metadata key value, specify only the key name in the

api-ref/source/share-access-rules.inc

@@ -3,7 +3,7 @@
 .. _get-access-rules-after-2-45:
 
 ====================================
-Share access rules (Since API v2.45)
+Share access rules (since API v2.45)
 ====================================
 
 Retrieve details about access rules
@@ -13,6 +13,7 @@ Describe share access rule
 
 .. rest_method::  GET /v2/{tenant_id}/share-access-rules/{access_id}
 
+.. versionadded:: 2.45
 
 Retrieve details about a specified access rule.
 
@@ -66,6 +67,8 @@ List share access rules
 
 .. rest_method::  GET /v2/{tenant_id}/share-access-rules?share_id={share-id}
 
+.. versionadded:: 2.45
+
 Lists the share access rules on a share.
 
 .. note::

api-ref/source/share-actions.inc

@@ -170,18 +170,21 @@ Request example
    :language: javascript
 
 
-List access rules (versions 1.0 to 2.44)
+List access rules (DEPRECATED)
-========================================
+==============================
+
+.. warning::
+
+   This API is deprecated starting with microversion 2.45 and requests to
+   this API will fail with a 404 starting from microversion 2.45. Use
+   :ref:`List share access rules <get-access-rules-after-2-45>` API
+   instead of this API from version 2.45.
 
 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action
 
 Lists access rules for a share. The Access ID returned is necessary to deny
 access.
 
-.. note::
-  Use :ref:`List share access rules <get-access-rules-after-2-45>` API
-  instead of this API from version 2.45
-
 Response codes
 --------------
 
@@ -452,13 +455,15 @@ Response parameters
 There is no body content for the response.
 
 
-Revert share to snapshot
+Revert share to snapshot (since API v2.27)
-========================
+==========================================
 
 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action
 
+.. versionadded:: 2.27
+
 Reverts a share to the specified snapshot, which must be the most recent one
-known to manila. This API is available in versions later than or equal to 2.27.
+known to manila.
 
 Response codes
 --------------

api-ref/source/share-export-locations.inc

@@ -17,6 +17,8 @@ List export locations
 
 .. rest_method::  GET /v2/{tenant_id}/shares/{share_id}/export_locations
 
+.. versionadded:: 2.9
+
 Lists all export locations for a share.
 
 Response codes
@@ -64,6 +66,8 @@ Show single export location
 
 .. rest_method::  GET /v2/{tenant_id}/shares/{share_id}/export_locations/​{export_location_id}​
 
+.. versionadded:: 2.9
+
 Show details of an export location belonging to a share.
 
 Response codes

api-ref/source/share-group-snapshots.inc

@@ -27,6 +27,8 @@ List share group snapshots
 
 .. rest_method::  GET /v2/{tenant_id}/share-group-snapshots
 
+.. versionadded:: 2.31
+
 Lists all share group snapshots.
 
 Response codes
@@ -79,6 +81,8 @@ List share group snapshots with details
 
 .. rest_method::  GET /v2/{tenant_id}/share-group-snapshots/detail
 
+.. versionadded:: 2.31
+
 Lists all share group snapshots with details.
 
 Response codes
@@ -137,6 +141,8 @@ List share group snapshots members
 
 .. rest_method::  GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/members
 
+.. versionadded:: 2.31
+
 Lists all share group snapshots members.
 
 Response codes
@@ -186,6 +192,8 @@ Show share group snapshot details
 
 .. rest_method::  GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
 
+.. versionadded:: 2.31
+
 Shows details for a share group snapshot.
 
 Response codes
@@ -236,6 +244,8 @@ Create share group snapshot
 
 .. rest_method::  POST /v2/{tenant_id}/share-group-snapshots
 
+.. versionadded:: 2.31
+
 Creates a snapshot from a share.
 
 Response codes
@@ -296,6 +306,8 @@ Reset share group snapshot state
 
 .. rest_method::  POST /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/action
 
+.. versionadded:: 2.31
+
 Administrator only. Explicitly updates the state of a share group snapshot.
 
 Use the ``policy.json`` file to grant permissions for this action
@@ -336,6 +348,8 @@ Update share group snapshot
 
 .. rest_method::  PUT /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
 
+.. versionadded:: 2.31
+
 Updates a share group snapshot.
 
 Response codes
@@ -396,6 +410,8 @@ Delete share group snapshot
 
 .. rest_method::  DELETE /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
 
+.. versionadded:: 2.31
+
 Deletes a share group snapshot.
 
 Response codes

api-ref/source/share-group-types.inc

@@ -39,6 +39,8 @@ List share group types
 
 .. rest_method::  GET /v2/{tenant_id}/share-group-types
 
+.. versionadded:: 2.31
+
 Lists all share group types.
 
 Response codes
@@ -79,6 +81,8 @@ List default share group types
 
 .. rest_method::  GET /v2/{tenant_id}/share-group-types/default
 
+.. versionadded:: 2.31
+
 Lists default share group types.
 
 Response codes
@@ -126,6 +130,8 @@ List share group types extra specs
 
 .. rest_method::  GET /v2/{tenant_id}/share-group-types/{share_group_type_id}/group_specs
 
+.. versionadded:: 2.31
+
 Lists the extra specifications for a share group type.
 
 Response codes
@@ -169,6 +175,8 @@ Create share group type
 
 .. rest_method::  POST /v2/{tenant_id}/share-group-types
 
+.. versionadded:: 2.31
+
 Creates a share group type.
 
 Response codes
@@ -227,6 +235,8 @@ Show share group type access details
 
 .. rest_method::  GET /v2/{tenant_id}/share-group-types/{share_group_type_id}/share_type_access
 
+.. versionadded:: 2.31
+
 Shows access details for a share group type.
 
 You can view access details for private share group types only.
@@ -273,6 +283,8 @@ Set extra spec for share group type
 
 .. rest_method::  POST /v2/{tenant_id}/share-group-types/{share_group_type_id}/group_specs
 
+.. versionadded:: 2.31
+
 Sets an extra specification for the share group type.
 
 Response codes
@@ -324,6 +336,8 @@ Unset an group spec
 
 .. rest_method::  DELETE /v2/{tenant_id}/share-group-types/{share_group_type_id}/group-specs/{group_spec_key}
 
+.. versionadded:: 2.31
+
 Unsets an extra specification for the share type.
 
 Response codes
@@ -355,6 +369,8 @@ Add share group type access
 
 .. rest_method::  POST /v2/{tenant_id}/share-group-types/{share_group_type_id}/action
 
+.. versionadded:: 2.31
+
 Adds share group type access for a project.
 
 You can add access to private share group types only.
@@ -395,6 +411,8 @@ Remove share group type access
 
 .. rest_method::  POST /v2/{tenant_id}/share-group-types/{share_group_type_id}/action
 
+.. versionadded:: 2.31
+
 Removes share group type access from a project.
 
 You can remove access from private share group types only.
@@ -434,6 +452,8 @@ Delete share group type
 
 .. rest_method::  DELETE /v2/{tenant_id}/share-group-types/{share_group_type_id}
 
+.. versionadded:: 2.31
+
 Deletes a share group type.
 
 Response codes

api-ref/source/share-groups.inc

@@ -28,6 +28,8 @@ List share groups
 
 .. rest_method::  GET /v2/{tenant_id}/share_groups
 
+.. versionadded:: 2.31
+
 Lists all share groups.
 
 Response codes
@@ -89,6 +91,8 @@ Show share group details
 
 .. rest_method::  GET /v2/{tenant_id}/share_groups/{share_group_id}
 
+.. versionadded:: 2.31
+
 Shows details for a share group.
 
 
@@ -146,6 +150,8 @@ Create share group
 
 .. rest_method::  POST /v2/{tenant_id}/share_groups
 
+.. versionadded:: 2.31
+
 Creates a share group.
 
 Response codes
@@ -216,6 +222,8 @@ Reset share group state
 
 .. rest_method::  POST /v2/{tenant_id}/share-groups/{share_group_id}/action
 
+.. versionadded:: 2.31
+
 Administrator only. Explicitly updates the state of a share group.
 
 Use the ``policy.json`` file to grant permissions for this action
@@ -257,6 +265,8 @@ Update share group
 
 .. rest_method::  PUT /v2/{tenant_id}/share-groups/{share_group_id}
 
+.. versionadded:: 2.31
+
 Updates a share group.
 
 Response codes
@@ -322,6 +332,8 @@ Delete share group
 
 .. rest_method::  DELETE /v2/{tenant_id}/share-groups/{share_group_id}
 
+.. versionadded:: 2.31
+
 Deletes a share group.
 
 Response codes

api-ref/source/share-instance-export-locations.inc

@@ -19,6 +19,8 @@ List export locations
 
 .. rest_method::  GET /v2/{tenant_id}/share_instances/{share_instance_id}/export_locations
 
+.. versionadded:: 2.9
+
 Response codes
 --------------
 
@@ -64,6 +66,7 @@ Show single export location
 
 .. rest_method::  GET /v2/{tenant_id}/share_instances/{share_instance_id}/export_locations/{export_location_id}
 
+.. versionadded:: 2.9
 
 Response codes
 --------------

api-ref/source/share-instances.inc

@@ -14,6 +14,8 @@ List share instances
 
 .. rest_method::  GET /v2/{tenant_id}/share_instances
 
+.. versionadded:: 2.3
+
 Lists all share instances.
 
 Response codes
@@ -51,6 +53,7 @@ Response parameters
    - replica_state: replica_state
    - export_location: export_location
    - export_locations: export_locations
+   - cast_rules_to_readonly: share_instance_cast_rules_to_readonly
    - share_network_id: share_network_id_4
    - share_server_id: share_server_id
    - host: host_6
@@ -68,6 +71,8 @@ Show share instance details
 
 .. rest_method::  GET /v2/{tenant_id}/share_instances/{share_instance_id}
 
+.. versionadded:: 2.3
+
 Shows details for a share instance.
 
 Response codes
@@ -105,6 +110,7 @@ Response parameters
    - replica_state: replica_state
    - export_location: export_location
    - export_locations: export_locations
+   - cast_rules_to_readonly: share_instance_cast_rules_to_readonly
    - share_network_id: share_network_id_4
    - share_server_id: share_server_id
    - host: host_6
@@ -122,6 +128,8 @@ Reset share instance state
 
 .. rest_method::  POST /v2/{tenant_id}/share_instances/{share_instance_id}/action
 
+.. versionadded:: 2.3
+
 Administrator only. Explicitly updates the state of a share instance.
 
 Use the ``policy.json`` file to grant permissions for this action
@@ -162,6 +170,8 @@ Force-delete share instance
 
 .. rest_method::  POST /v2/{tenant_id}/share_instances/{share_instance_id}/action
 
+.. versionadded:: 2.3
+
 Administrator only. Force-deletes a share instance.
 
 Use the ``policy.json`` file to grant permissions for this action

api-ref/source/share-migration.inc

@@ -1,7 +1,7 @@
 .. -*- rst -*-
 
 ================================
-Share Migration (Since API v2.5)
+Share Migration (since API v2.5)
 ================================
 As an administrator, you can migrate a share with its data from one
 location to another in a manner that is transparent to users and workloads.
@@ -20,11 +20,19 @@ Possible use cases for data migration include:
     #experimental-apis>`_ .
 
 
-Migrate share (versions 2.5 to 2.14)
+Migrate share (DEPRECATED)
-=========================================
+==========================
+
+.. warning::
+
+   This API is deprecated starting with microversion 2.15 and requests to
+   this API will fail with a 404 starting from microversion 2.15. Please see
+   the new experimental API below.
 
 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action
 
+.. versionadded:: 2.5
+
 Migrates a share from one back end to another.
 
 You can migrate a share from one back end to another but both back
@@ -61,11 +69,13 @@ Request
    - force_host_copy: force_host_copy
 
 
-Start Migration (Since version 2.15)
+Start Migration (since API v2.15)
-====================================
+=================================
 
 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action
 
+.. versionadded:: 2.15
+
 Initiates share migration. This API will initiate the share data copy to the
 new host. The copy operation is non-disruptive.
 
@@ -97,11 +107,13 @@ Request
    - force_host_copy: force_host_copy
 
 
-Complete Migration (Since version 2.15)
+Complete Migration (since API v2.15)
 =======================================
 
 .. rest_method::  POST /v2/{tenant_id}/shares/{share_id}/action
 
+.. versionadded:: 2.15
+
 Completes share migration. This API will initiate the switch-over from the
 source to destination share. This operation is disruptive.
 

api-ref/source/share-replica-export-locations.inc

@@ -13,6 +13,8 @@ List export locations
 
 .. rest_method::  GET /v2/{tenant_id}/share-replicas/{share_replica_id}/export-locations
 
+.. versionadded:: 2.47
+
 Response codes
 --------------
 
@@ -60,6 +62,8 @@ Show single export location
 
 .. rest_method::  GET /v2/{tenant_id}/share-replicas/{share_replica_id}/export-locations/{export-location-id}
 
+.. versionadded:: 2.47
+
 
 Response codes
 --------------

api-ref/source/share-replicas.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-===================================
+================================
-Share replicas (Since version 2.11)
+Share replicas (since API v2.11)
-===================================
+================================
 
 Share replicas are the replicated copies of the existing share. You can use
 Share Replicas to sync data so that each share replica has an identical copy
@@ -57,6 +57,8 @@ Create share replica
 
 .. rest_method::  POST /v2/{tenant_id}/share-replicas
 
+.. versionadded:: 2.11
+
 Create a share replica for the share.
 
 Response codes
@@ -118,6 +120,8 @@ Promote share replica
 
 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
 
+.. versionadded:: 2.11
+
 Promotes a replica to ``active`` replica state.
 
 Response codes
@@ -148,6 +152,8 @@ Resync share replica
 
 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
 
+.. versionadded:: 2.11
+
 Resync a replica with its ``active`` mirror.
 
 Response codes
@@ -178,6 +184,8 @@ List share replicas
 
 .. rest_method::  GET /v2/{tenant_id}/share-replicas?share_id={share_id}
 
+.. versionadded:: 2.11
+
 Lists share replicas.
 
 Response codes
@@ -224,6 +232,8 @@ List share replicas with details
 
 .. rest_method::  GET /v2/{tenant_id}/share-replicas/detail?share_id={share_id}
 
+.. versionadded:: 2.11
+
 Lists share replicas with details.
 
 Response codes
@@ -276,6 +286,8 @@ Show share replica
 
 .. rest_method::  GET /v2/{tenant_id}/share-replicas/{share_replica_id}
 
+.. versionadded:: 2.11
+
 Show a share replica.
 
 Response codes
@@ -329,6 +341,8 @@ Reset status of the share replica
 
 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
 
+.. versionadded:: 2.11
+
 Administrator only. Explicitly updates the ``status`` of a share replica.
 
 Use the ``policy.json`` file to grant permissions for this action
@@ -370,6 +384,8 @@ Reset replica_state of the share replica
 
 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
 
+.. versionadded:: 2.11
+
 Administrator only. Explicitly updates the ``replica state`` of a share replica.
 
 Use the ``policy.json`` file to grant permissions for this action
@@ -411,6 +427,8 @@ Delete share replica
 
 .. rest_method::  DELETE /v2/{tenant_id}/share-replicas/{share_replica_id}
 
+.. versionadded:: 2.11
+
 Deletes a share replica.
 
 Response codes
@@ -446,6 +464,8 @@ Force-delete share replica
 
 .. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
 
+.. versionadded:: 2.11
+
 Administrator only. Force-deletes a share replica in any state.
 
 Use the ``policy.json`` file to grant permissions for this action

api-ref/source/snapshot-instances.inc

@@ -21,6 +21,8 @@ List share snapshot instances
 
 .. rest_method::  GET /v2/{tenant_id}/snapshot-instances
 
+.. versionadded:: 2.19
+
 Lists all share snapshot instances.
 
 Response codes
@@ -65,6 +67,8 @@ List share snapshot instances with details
 
 .. rest_method::  GET /v2/{tenant_id}/snapshot-instances/detail
 
+.. versionadded:: 2.19
+
 Lists all share snapshot instances with details.
 
 Response codes
@@ -115,6 +119,8 @@ Show share snapshot instance details
 
 .. rest_method::  GET /v2/{tenant_id}/snapshot-instances/{snapshot_instance_id}
 
+.. versionadded:: 2.19
+
 Shows details for a share snapshot instance.
 
 Response codes
@@ -166,6 +172,8 @@ Reset share snapshot instance state
 
 .. rest_method::  POST /v2/{tenant_id}/snapshot-instances/{snapshot_instance_id}/action
 
+.. versionadded:: 2.19
+
 Administrator only. Explicitly updates the state of a share snapshot instance.
 
 Use the ``policy.json`` file to grant permissions for this action

api-ref/source/user-messages.inc

@@ -22,6 +22,8 @@ List user messages
 
 .. rest_method::  GET /v2/{tenant_id}/messages
 
+.. versionadded:: 2.37
+
 Lists all user messages.
 
 
@@ -83,6 +85,8 @@ Show user message details
 
 .. rest_method::  GET /v2/{tenant_id}/messages/{message_id}
 
+.. versionadded:: 2.37
+
 Shows details for a user message.
 
 Response codes
@@ -134,6 +138,8 @@ Delete message
 
 .. rest_method::  DELETE /v2/{tenant_id}/messages/{message_id}
 
+.. versionadded:: 2.37
+
 Deletes a user message.
 
 Response codes

manila/api/openstack/rest_api_version_history.rst

@@ -271,7 +271,7 @@ user documentation.
   only within specific availability zones. The extra-spec allows using
   comma separated names of one or more availability zones.
 
-2.49
+2.49 (Maximum in Stein)
-----
+-----------------------
   Added Manage/Unmanage Share Server APIs. Updated Manage/Unmanage Shares and
   Snapshots APIs to work in ``driver_handles_shares_servers`` enabled mode.