Cache management API endpoints

This change adds the new cache API endpoints and their related
new policies.

Implements-bp: https://blueprints.launchpad.net/glance/+spec/cache-api
Change-Id: I69162e19bf095ef11fbac56a1ea2159d1caefba7

3 files changed, 93 insertions, 0 deletions

diff --git a/api-ref/source/v2/cache-manage.inc b/api-ref/source/v2/cache-manage.inc
new file mode 100644
index 000000000..1993cb191
--- /dev/null
+++ b/api-ref/source/v2/cache-manage.inc
@@ -0,0 +1,84 @@
+.. -*- rst -*-
+
+Cache Manage
+************
+
+List and manage the cache.
+
+
+Query cache status
+~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v2/cache/
+
+Lists all images in cache or queue.
+*(Since Image API v2.14)*
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403
+
+
+Request
+-------
+
+No request parameters.
+
+
+Queue image
+~~~~~~~~~~~
+
+.. rest_method::  PUT /v2/cache/{image_id}/
+
+Queues image for caching.
+*(Since Image API v2.14)*
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403, 404
+
+
+Request
+-------
+
+   - image_id: image_id-in-path
+
+
+Delete image from cache
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  DELETE /v2/cache/{image_id}/
+
+Deletes a image from cache.
+*(Since Image API v2.14)*
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 403, 404
+
+
+Request
+-------
+
+   - image_id: image_id-in-path
+
+
+Clear images from cache
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  DELETE /v2/cache/
+
+Clears the cache and its queue.
+*(Since Image API v2.14)*
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 403
+
+
+Request
+-------
+
+.. rest_parameters:: images-parameters.yaml
+
+    - x-image-cache-clear-target: cache-clear-header
diff --git a/api-ref/source/v2/images-parameters.yaml b/api-ref/source/v2/images-parameters.yaml
index 459a20b1c..a99bbd601 100644
--- a/api-ref/source/v2/images-parameters.yaml
+++ b/api-ref/source/v2/images-parameters.yaml
@@ -1,4 +1,12 @@
 # variables in header
+cache-clear-header:
+  description: |
+    A keyword indicating 'cache', 'queue' or empty string to indicate the delete
+    API to delete images from cache or queue or delete from both.   If this header
+    is missing then all cached and queued images for caching will be deleted.
+  in: header
+  required: false
+  type: string
 Content-Length:
   description: |
     The length of the body in octets (8-bit bytes)
diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst
index f18dfbf31..61b2eb7cd 100644
--- a/api-ref/source/v2/index.rst
+++ b/api-ref/source/v2/index.rst
@@ -33,3 +33,4 @@ Image Service API v2 (CURRENT)
 .. include:: discovery.inc
 .. include:: tasks.inc
 .. include:: tasks-schemas.inc
+.. include:: cache-manage.inc