[api-ref] update cache manage API info

Change-Id: If95fcb6beb17fd4ca337da58bc8fb03bbde25b03
Closes-bug: #1971176

3 files changed, 62 insertions, 4 deletions

diff --git a/api-ref/source/v2/cache-manage-parameters.yaml b/api-ref/source/v2/cache-manage-parameters.yaml
new file mode 100644
index 000000000..a8771e2b1
--- /dev/null
+++ b/api-ref/source/v2/cache-manage-parameters.yaml
@@ -0,0 +1,25 @@
+cached_images:
+  description: |
+    A list of cached image JSON objects, possibly empty, where each
+    object contains the following fields:
+
+    ``image_id``
+        The id of the cached image
+    ``hits``
+        The number of cache hits for this image.
+    ``last_accessed``
+        Epoch time when the cached image was most recently accessed.
+    ``last_modified``
+        Epoch time when the cached image was installed into the cache.
+    ``size``
+        Size in bytes of the cached image.
+  in: body
+  required: true
+  type: array
+queued_images:
+  description: |
+    A list of image ids, possibly empty, of images queued to be
+    cached, listed in the order in which they will be processed.
+  in: body
+  required: true
+  type: array
diff --git a/api-ref/source/v2/cache-manage.inc b/api-ref/source/v2/cache-manage.inc
index 1993cb191..93379f434 100644
--- a/api-ref/source/v2/cache-manage.inc
+++ b/api-ref/source/v2/cache-manage.inc
@@ -9,7 +9,7 @@ List and manage the cache.
 Query cache status
 ~~~~~~~~~~~~~~~~~~
 
-.. rest_method::  GET /v2/cache/
+.. rest_method::  GET /v2/cache
 
 Lists all images in cache or queue.
 *(Since Image API v2.14)*
@@ -24,11 +24,25 @@ Request
 
 No request parameters.
 
+Response Parameters
+-------------------
+
+.. rest_parameters:: cache-manage-parameters.yaml
+
+   - cached_images: cached_images
+   - queued_images: queued_images
+
+Response Example
+----------------
+
+.. literalinclude:: samples/cache-list-response.json
+   :language: json
+
 
 Queue image
 ~~~~~~~~~~~
 
-.. rest_method::  PUT /v2/cache/{image_id}/
+.. rest_method::  PUT /v2/cache/{image_id}
 
 Queues image for caching.
 *(Since Image API v2.14)*
@@ -41,13 +55,15 @@ Error response codes: 400, 401, 403, 404
 Request
 -------
 
+.. rest_parameters:: images-parameters.yaml
+
    - image_id: image_id-in-path
 
 
 Delete image from cache
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-.. rest_method::  DELETE /v2/cache/{image_id}/
+.. rest_method::  DELETE /v2/cache/{image_id}
 
 Deletes a image from cache.
 *(Since Image API v2.14)*
@@ -60,13 +76,15 @@ Error response codes: 400, 401, 403, 404
 Request
 -------
 
+.. rest_parameters:: images-parameters.yaml
+
    - image_id: image_id-in-path
 
 
 Clear images from cache
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-.. rest_method::  DELETE /v2/cache/
+.. rest_method::  DELETE /v2/cache
 
 Clears the cache and its queue.
 *(Since Image API v2.14)*
diff --git a/api-ref/source/v2/samples/cache-list-response.json b/api-ref/source/v2/samples/cache-list-response.json
new file mode 100644
index 000000000..d5b4fc3dd
--- /dev/null
+++ b/api-ref/source/v2/samples/cache-list-response.json
@@ -0,0 +1,15 @@
+{
+    "cached_images": [
+        {
+            "image_id": "fe05d6c9-ef02-4161-9056-81ed046f3024",
+            "hits": 0,
+            "last_accessed": 1651504844.0860524,
+            "last_modified": 1651504844.0860524,
+            "size": 987654
+        }
+    ],
+    "queued_images": [
+        "e34e6e2f-fe16-420d-ad36-cebf69506106",
+        "6b9fbf2b-3031-429a-80b1-b509e4c44046"
+    ]
+}