Documentation for new results filtering in the API and client.

doc/source/client.rst

@@ -63,6 +63,57 @@ Using Glance's Client, we can do this using the following code
 
   print c.get_images_detailed()
 
+Filtering Images Returned via ``get_images()`` and ``get_images_detailed()``
+----------------------------------------------------------------------------
+
+Both the ``get_images()`` and ``get_images_detailed()`` methods take query
+parameters that serve to filter the returned list of images. 
+
+When calling, simple pass an optional dictionary to the method containing
+the filters by which you wish to limit results, with the filter keys being one
+or more of the below:
+
+* ``name: NAME``
+
+  Filters images having a ``name`` attribute matching ``NAME``.
+
+* ``container_format: FORMAT``
+
+  Filters images having a ``container_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``disk_format: FORMAT``
+
+  Filters images having a ``disk_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``status: STATUS``
+
+  Filters images having a ``status`` attribute matching ``STATUS``
+
+  For more information, see :doc:`About Image Statuses <statuses>`
+
+* ``size_min: BYTES``
+
+  Filters images having a ``size`` attribute greater than or equal to ``BYTES``
+
+* ``size_max: BYTES``
+
+  Filters images having a ``size`` attribute less than or equal to ``BYTES``
+
+Here's a quick example that will return all images less than or equal to 5G
+in size and in the `saving` status.
+
+.. code-block:: python
+
+  from glance.client import Client
+
+  c = Client("glance.example.com", 9292)
+
+  filters = {'status': 'saving', 'size_max': (5 * 1024 * 1024 * 1024)}
+  print c.get_images_detailed(filters)
 
 Requesting Detailed Metadata on a Specific Image
 ------------------------------------------------
@@ -86,7 +137,6 @@ first public image returned, we can use the following code
 
   print c.get_image_meta("http://glance.example.com/images/1")
 
-
 Retrieving a Virtual Machine Image
 ----------------------------------
 

doc/source/glanceapi.rst

@@ -92,6 +92,42 @@ JSON-encoded mapping in the following format::
 
   The `checksum` field is an MD5 checksum of the image file data
 
+Filtering Images Returned via ``GET /images`` and ``GET /images/detail``
+------------------------------------------------------------------------
+
+Both the ``GET /images`` and ``GET /images/detail`` requests take query
+parameters that serve to filter the returned list of images. The following
+list details these query parameters.
+
+* ``name=NAME``
+
+  Filters images having a ``name`` attribute matching ``NAME``.
+
+* ``container_format=FORMAT``
+
+  Filters images having a ``container_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``disk_format=FORMAT``
+
+  Filters images having a ``disk_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``status=STATUS``
+
+  Filters images having a ``status`` attribute matching ``STATUS``
+
+  For more information, see :doc:`About Image Statuses <statuses>`
+
+* ``size_min=BYTES``
+
+  Filters images having a ``size`` attribute greater than or equal to ``BYTES``
+
+* ``size_max=BYTES``
+
+  Filters images having a ``size`` attribute less than or equal to ``BYTES``
 
 Requesting Detailed Metadata on a Specific Image
 ------------------------------------------------

doc/source/registries.rst

@@ -46,6 +46,43 @@ The following is a brief description of the Glance API::
   PUT     /images/<ID>    Update metadata about an existing image
   DELETE  /images/<ID>    Remove an image's metadata from the registry
 
+Filtering Images Returned via ``GET /images`` and ``GET /images/detail``
+------------------------------------------------------------------------
+
+Both the ``GET /images`` and ``GET /images/detail`` requests take query
+parameters that serve to filter the returned list of images. The following
+list details these query parameters.
+
+* ``name=NAME``
+
+  Filters images having a ``name`` attribute matching ``NAME``.
+
+* ``container_format=FORMAT``
+
+  Filters images having a ``container_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``disk_format=FORMAT``
+
+  Filters images having a ``disk_format`` attribute matching ``FORMAT``
+
+  For more information, see :doc:`About Disk and Container Formats <formats>`
+
+* ``status=STATUS``
+
+  Filters images having a ``status`` attribute matching ``STATUS``
+
+  For more information, see :doc:`About Image Statuses <statuses>`
+
+* ``size_min=BYTES``
+
+  Filters images having a ``size`` attribute greater than or equal to ``BYTES``
+
+* ``size_max=BYTES``
+
+  Filters images having a ``size`` attribute less than or equal to ``BYTES``
+
 ``POST /images``
 ----------------