Merge "Update api-ref for tag filtering"

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:

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``.

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}

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'))

releasenotes/notes/add-api-tag-filtering-8bfb3c3b7cfd6afe.yaml

@@ -0,0 +1,4 @@
+---
+features:
+  - |
+    You can now filter API queries by the object tag.