From 7a93af1e61bc57f9ce1c10940a1337a57e435b42 Mon Sep 17 00:00:00 2001
From: Pieter Lexis <pieter.lexis@powerdns.com>
Date: Thu, 6 Sep 2018 12:23:13 +0200
Subject: [PATCH] Document authoritative server cache endpoint

---
 docs/http-api/cache.rst                       | 12 +++++++
 docs/http-api/index.rst                       |  1 +
 .../swagger/authoritative-api-swagger.yaml    | 34 +++++++++++++++++++
 3 files changed, 47 insertions(+)
 create mode 100644 docs/http-api/cache.rst

diff --git a/docs/http-api/cache.rst b/docs/http-api/cache.rst
new file mode 100644
index 000000000..9437efb04
--- /dev/null
+++ b/docs/http-api/cache.rst
@@ -0,0 +1,12 @@
+Cache
+=====
+
+Endpoints
+---------
+.. openapi:: swagger/authoritative-api-swagger.yaml
+  :paths: /servers/{server_id}/cache/flush
+
+Objects
+-------
+.. openapi:: swagger/authoritative-api-swagger.yaml
+  :definitions: CacheFlushResult
diff --git a/docs/http-api/index.rst b/docs/http-api/index.rst
index 7a159a8e2..91b4bc0c7 100644
--- a/docs/http-api/index.rst
+++ b/docs/http-api/index.rst
@@ -103,3 +103,4 @@ The API exposes several endpoints and objects:
   metadata
   search
   statistics
+  cache
diff --git a/docs/http-api/swagger/authoritative-api-swagger.yaml b/docs/http-api/swagger/authoritative-api-swagger.yaml
index 4746798b7..6d0212187 100644
--- a/docs/http-api/swagger/authoritative-api-swagger.yaml
+++ b/docs/http-api/swagger/authoritative-api-swagger.yaml
@@ -58,6 +58,29 @@ paths:
           schema:
             $ref: '#/definitions/Server'
 
+  '/servers/{server_id}/cache/flush':
+    put:
+      summary: Flush a cache-entry by name
+      operationId: cacheFlushByName
+      tags:
+        - servers
+      parameters:
+        - name: server_id
+          in: path
+          required: true
+          description: The id of the server to retrieve
+          type: string
+        - name: domain
+          in: query
+          required: true
+          description: The domain name to flush from the cache
+          type: string
+      responses:
+        '200':
+          description: Flush successful
+          schema:
+            $ref: '#/definitions/CacheFlushResult'
+
   '/servers/{server_id}/zones':
     get:
       summary: List all Zones in a server
@@ -1090,3 +1113,14 @@ definitions:
       bits:
         type: integer
         description: 'The size of the key'
+
+  CacheFlushResult:
+    title: CacheFlushResult
+    description: 'The result of a cache-flush'
+    properties:
+      count:
+        type: number
+        description: 'Amount of entries flushed'
+      result:
+        type: string
+        description: 'A message about the result like "Flushed cache"'
-- 
2.50.0