From fb0bbb98269f735177b00afe605946b439871acd Mon Sep 17 00:00:00 2001
From: Michael Johnson <johnsomor@gmail.com>
Date: Mon, 21 Jan 2019 16:53:14 -0800
Subject: [PATCH] Update api-ref for tag filtering

This patch also updates the API version to 2.5 to represent the tags
support.

Change-Id: Ia57724c231c10efad9cee46be4969fa276fff8b1
Co-Authored-By: Lingxian Kong <anlin.kong@gmail.com>
---
 api-ref/source/parameters.yaml                |  2 +
 api-ref/source/v2/general.inc                 | 56 +++++++++++++++++++
 octavia/api/root_controller.py                |  3 +
 .../functional/api/test_root_controller.py    |  4 +-
 ...dd-api-tag-filtering-8bfb3c3b7cfd6afe.yaml |  4 ++
 5 files changed, 67 insertions(+), 2 deletions(-)
 create mode 100644 releasenotes/notes/add-api-tag-filtering-8bfb3c3b7cfd6afe.yaml

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 456a1108c3..dd88c56a63 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1100,12 +1100,14 @@ tags:
   description: |
     A list of simple strings assigned to the resource.
   in: body
+  min_version: 2.5
   required: true
   type: list
 tags-optional:
   description: |
     A list of simple strings assigned to the resource.
   in: body
+  min_version: 2.5
   required: false
   type: list
 timeout_client_data:
diff --git a/api-ref/source/v2/general.inc b/api-ref/source/v2/general.inc
index dc70eb730e..902606c26c 100644
--- a/api-ref/source/v2/general.inc
+++ b/api-ref/source/v2/general.inc
@@ -161,6 +161,62 @@ Octavia does not offer an OR mechanism for filters.
 Alternatively, you can issue a distinct request for each filter and build a
 response set from the received responses on the client-side.
 
+Filtering by Tags
+-----------------
+
+**New in version 2.5**
+
+Most Octavia resources support adding tags to the resource attributes.
+Octavia supports advanced filtering using these tags. The following tag
+filters are supported by the Octavia API:
+
+- ``tags`` - Return the list of entities that have this tag or tags.
+- ``tags-any`` - Return the list of entities that have one or more of the
+  given tags.
+- ``not-tags`` - Return the list of entities that do not have one or more
+  of the given tags.
+- ``not-tags-any`` - Return the list of entities that do not have at least
+  one of the given tags.
+
+When supplying a list of tags, the tags should be provided in a comma seperated
+list.
+
+For example, if you would like to get the list of load balancers with both the
+"red" and "blue" tags you would request:
+
+.. code::
+
+    GET /v2/lbaas/loadbalancers?tags=red,blue
+
+To get a list of load balancers that have the "red" or "blue" tag, you would
+request:
+
+.. code::
+
+    GET /v2/lbaas/loadbalancers?tags-any=red,blue
+
+For a list of load balancers that do not have the "red" tag, you would request:
+
+.. code::
+
+    GET /v2/lbaas/loadbalancers?not-tags=red
+
+To get a list of load balancers that don't have either the "red" or "blue" tag
+you would request:
+
+.. code::
+
+    GET /v2/lbaas/loadbalancers?not-tags-any=red,blue
+
+Tag filters can also be combined in the same request:
+
+.. code::
+
+    GET /v2/lbaas/loadbalancers?tags=red,blue&tags-any=green,orange
+
+Column Selection
+----------------
+
 By default, Octavia returns all attributes for any show or list call. The
 Octavia API v2 has a mechanism to limit the set of attributes returned.
 For example, return ``id``.
diff --git a/octavia/api/root_controller.py b/octavia/api/root_controller.py
index 58a9ff2344..91c505bec4 100644
--- a/octavia/api/root_controller.py
+++ b/octavia/api/root_controller.py
@@ -81,4 +81,7 @@ class RootController(rest.RestController):
                                 '2018-12-18T00:00:00Z', host_url)
             self._add_a_version(versions, 'v2.4', 'v2', 'CURRENT',
                                 '2018-12-19T00:00:00Z', host_url)
+            # Tags
+            self._add_a_version(versions, 'v2.5', 'v2', 'CURRENT',
+                                '2019-01-21T00:00:00Z', host_url)
         return {'versions': versions}
diff --git a/octavia/tests/functional/api/test_root_controller.py b/octavia/tests/functional/api/test_root_controller.py
index 0578547600..38ca8da97c 100644
--- a/octavia/tests/functional/api/test_root_controller.py
+++ b/octavia/tests/functional/api/test_root_controller.py
@@ -46,7 +46,7 @@ class TestRootController(base_db_test.OctaviaDBTestBase):
         versions = self._get_versions_with_config(
             api_v1_enabled=True, api_v2_enabled=True)
         version_ids = tuple(v.get('id') for v in versions)
-        self.assertEqual(6, len(version_ids))
+        self.assertEqual(7, len(version_ids))
         self.assertIn('v1', version_ids)
         self.assertIn('v2.0', version_ids)
         self.assertIn('v2.1', version_ids)
@@ -72,7 +72,7 @@ class TestRootController(base_db_test.OctaviaDBTestBase):
     def test_api_v1_disabled(self):
         versions = self._get_versions_with_config(
             api_v1_enabled=False, api_v2_enabled=True)
-        self.assertEqual(5, len(versions))
+        self.assertEqual(6, len(versions))
         self.assertEqual('v2.0', versions[0].get('id'))
         self.assertEqual('v2.1', versions[1].get('id'))
         self.assertEqual('v2.2', versions[2].get('id'))
diff --git a/releasenotes/notes/add-api-tag-filtering-8bfb3c3b7cfd6afe.yaml b/releasenotes/notes/add-api-tag-filtering-8bfb3c3b7cfd6afe.yaml
new file mode 100644
index 0000000000..4985ece2b8
--- /dev/null
+++ b/releasenotes/notes/add-api-tag-filtering-8bfb3c3b7cfd6afe.yaml
@@ -0,0 +1,4 @@
+---
+features:
+  - |
+    You can now filter API queries by the object tag.