api-ref: "hidden" images update17.0.0.0rc217.0.0

Update the api-ref for the "Operator maintained images lifecycle"
spec implemented in Rocky.

Change-Id: I8fcfb84579b655fd44759164508ce4532e4dd205

9 files changed, 43 insertions, 5 deletions

diff --git a/api-ref/source/v2/images-images-v2.inc b/api-ref/source/v2/images-images-v2.inc
index d10c796e0..54a3788ea 100644
--- a/api-ref/source/v2/images-images-v2.inc
+++ b/api-ref/source/v2/images-images-v2.inc
@@ -218,6 +218,7 @@ Response Parameters
    - name: name
    - os_hash_algo: os_hash_algo
    - os_hash_value: os_hash_value
+   - os_hidden: os_hidden
    - owner: owner
    - protected: protected
    - schema: schema-image
@@ -284,6 +285,7 @@ Response Parameters
    - name: name
    - os_hash_algo: os_hash_algo
    - os_hash_value: os_hash_value
+   - os_hidden: os_hidden
    - owner: owner
    - protected: protected
    - schema: schema-image
@@ -482,6 +484,7 @@ Request
    - status: status-in-query
    - tag: tag-in-query
    - visibility: visibility-in-query
+   - os_hidden: os_hidden-in-query
    - member_status: member_status-in-query
    - size_max: size_max
    - size_min: size_min
@@ -606,6 +609,7 @@ Response Parameters
    - owner: owner
    - os_hash_algo: os_hash_algo
    - os_hash_value: os_hash_value
+   - os_hidden: os_hidden
    - protected: protected
    - schema: schema-image
    - self: self
diff --git a/api-ref/source/v2/images-parameters.yaml b/api-ref/source/v2/images-parameters.yaml
index 113e4a54f..28535e0b4 100644
--- a/api-ref/source/v2/images-parameters.yaml
+++ b/api-ref/source/v2/images-parameters.yaml
@@ -165,6 +165,14 @@ name-in-query:
   in: query
   required: false
   type: string
+os_hidden-in-query:
+  description: |
+    When ``true``, filters the response to display only "hidden" images.  By
+    default, "hidden" images are not included in the image-list response.
+    *(Since Image API v2.7)*
+  in: query
+  required: false
+  type: boolean
 owner-in-query:
   description: |
     Filters the response by a project (also called a "tenant") ID.  Shows only
@@ -522,6 +530,18 @@ os_hash_value:
   in: body
   required: true
   type: string
+os_hidden:
+  description: |
+    This field controls whether an image is displayed in the default
+    image-list response.  A "hidden" image is out of date somehow (for
+    example, it may not have the latest updates applied) and hence should
+    not be a user's first choice, but it's not deleted because it may be
+    needed for server rebuilds.  By hiding it from the default image list,
+    it's easier for end users to find and use a more up-to-date version of
+    this image.  *(Since Image API v2.7)*
+  in: body
+  required: true
+  type: boolean
 owner:
   description: |
     An identifier for the owner of the image, usually the project (also
diff --git a/api-ref/source/v2/samples/image-create-response.json b/api-ref/source/v2/samples/image-create-response.json
index afcb822dc..fe948991e 100644
--- a/api-ref/source/v2/samples/image-create-response.json
+++ b/api-ref/source/v2/samples/image-create-response.json
@@ -17,6 +17,7 @@
     "checksum": null,
     "os_hash_algo": null,
     "os_hash_value": null,
+    "os_hidden": false,
     "owner": "bab7d5c60cd041a0a36f7c4b6e1dd978",
     "virtual_size": null,
     "min_ram": 0,
diff --git a/api-ref/source/v2/samples/image-details-deactivate-response.json b/api-ref/source/v2/samples/image-details-deactivate-response.json
index 66a5d5b1d..24ba58680 100644
--- a/api-ref/source/v2/samples/image-details-deactivate-response.json
+++ b/api-ref/source/v2/samples/image-details-deactivate-response.json
@@ -14,7 +14,8 @@
     "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
     "checksum": "64d7c1cd2b6f60c92c14662941cb7913",
     "os_hash_algo": "sha512",
-    "os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09"
+    "os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09",
+    "os_hidden": false,
     "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
     "size": 13167616,
     "min_ram": 0,
diff --git a/api-ref/source/v2/samples/image-show-response.json b/api-ref/source/v2/samples/image-show-response.json
index 9660d4fd0..33e3fd92e 100644
--- a/api-ref/source/v2/samples/image-show-response.json
+++ b/api-ref/source/v2/samples/image-show-response.json
@@ -14,7 +14,8 @@
     "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
     "checksum": "64d7c1cd2b6f60c92c14662941cb7913",
     "os_hash_algo": "sha512",
-    "os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09"
+    "os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09",
+    "os_hidden": false,
     "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
     "size": 13167616,
     "min_ram": 0,
diff --git a/api-ref/source/v2/samples/image-update-response.json b/api-ref/source/v2/samples/image-update-response.json
index 3211cc83d..ee5c5e0bb 100644
--- a/api-ref/source/v2/samples/image-update-response.json
+++ b/api-ref/source/v2/samples/image-update-response.json
@@ -10,7 +10,8 @@
     "name": "Fedora 17",
     "owner": "02a7fb2dd4ef434c8a628c511dcbbeb6",
     "os_hash_algo": "sha512",
-    "os_hash_value": "ef7d1ed957ffafefb324d50ebc6685ed03d0e64549762ba94a1c44e92270cdbb69d7437dd1e101d00dd41684aaecccad1edc5c2e295e66d4733025b052497844"
+    "os_hash_value": "ef7d1ed957ffafefb324d50ebc6685ed03d0e64549762ba94a1c44e92270cdbb69d7437dd1e101d00dd41684aaecccad1edc5c2e295e66d4733025b052497844",
+    "os_hidden": false,
     "protected": false,
     "schema": "/v2/schemas/image",
     "self": "/v2/images/2b61ed2b-f800-4da0-99ff-396b742b8646",
diff --git a/api-ref/source/v2/samples/images-list-response.json b/api-ref/source/v2/samples/images-list-response.json
index c44504b70..3d641be7c 100644
--- a/api-ref/source/v2/samples/images-list-response.json
+++ b/api-ref/source/v2/samples/images-list-response.json
@@ -16,7 +16,8 @@
             "file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
             "checksum": "64d7c1cd2b6f60c92c14662941cb7913",
             "os_hash_algo": "sha512",
-            "os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09"
+            "os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09",
+            "os_hidden": false,
             "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
             "size": 13167616,
             "min_ram": 0,
@@ -39,7 +40,8 @@
             "file": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c/file",
             "checksum": "afab0f79bac770d61d24b4d0560b5f70",
             "os_hash_algo": "sha512",
-            "os_hash_value": "ea3e20140df1cc65f53d4c5b9ee3b38d0d6868f61bbe2230417b0f98cef0e0c7c37f0ebc5c6456fa47f013de48b452617d56c15fdba25e100379bd0e81ee15ec"
+            "os_hash_value": "ea3e20140df1cc65f53d4c5b9ee3b38d0d6868f61bbe2230417b0f98cef0e0c7c37f0ebc5c6456fa47f013de48b452617d56c15fdba25e100379bd0e81ee15ec",
+            "os_hidden": false,
             "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
             "size": 476704768,
             "min_ram": 0,
diff --git a/api-ref/source/v2/samples/schemas-image-show-response.json b/api-ref/source/v2/samples/schemas-image-show-response.json
index 5232ac7d3..bec4935de 100644
--- a/api-ref/source/v2/samples/schemas-image-show-response.json
+++ b/api-ref/source/v2/samples/schemas-image-show-response.json
@@ -163,6 +163,10 @@
                 "string"
             ]
         },
+        "os_hidden": {
+            "description": "If true, image will not appear in default image list response.",
+            "type": "boolean"
+        },
         "os_version": {
             "description": "Operating system version as specified by the distributor",
             "is_base": false,
diff --git a/api-ref/source/v2/samples/schemas-images-list-response.json b/api-ref/source/v2/samples/schemas-images-list-response.json
index 3365b88e8..f1509702c 100644
--- a/api-ref/source/v2/samples/schemas-images-list-response.json
+++ b/api-ref/source/v2/samples/schemas-images-list-response.json
@@ -184,6 +184,10 @@
                             "string"
                         ]
                     },
+                    "os_hidden": {
+                        "description": "If true, image will not appear in default image list response.",
+                        "type": "boolean"
+                    },
                     "os_version": {
                         "description": "Operating system version as specified by the distributor",
                         "is_base": false,