Document API max_limit configuration option

The max_limit option in the [api] section of ironic.conf is not
obviously pointed out in API documentation. This may mislead a user into
believing that using the "limit" parameter when listing resources from
the API may return more resources than the API configuration actually
allows.

This change adds documentation regarding how the max_limit option
affects API usage.

Change-Id: Ic55b31758b144aa8ef8b048f3dd90a4ffeee6fa4
Closes-Bug: 1597834

api-ref/source/parameters.yaml

@@ -86,11 +86,13 @@ fields:
   type: array
 limit:
   description: |
-    Requests a page size of items. Returns a number
+    Requests a page size of items. Returns a number of items up to a limit
-    of items up to a limit value. Use the ``limit`` parameter to make
+    value. Use the ``limit`` parameter to make an initial limited request and
-    an initial limited request and use the ID of the last-seen item
+    use the ID of the last-seen item from the response as the ``marker``
-    from the response as the ``marker`` parameter value in a
+    parameter value in a subsequent limited request. This value cannot be
-    subsequent limited request.
+    larger than the ``max_limit`` option in the ``[api]`` section of the
+    configuration. If it is higher than ``max_limit``, only ``max-limit``
+    resources will be returned.
   in: query
   required: false
   type: integer

ironic/api/controllers/v1/chassis.py

@@ -198,6 +198,9 @@ class ChassisController(rest.RestController):
 
         :param marker: pagination marker for large data sets.
         :param limit: maximum number of resources to return in a single result.
+                      This value cannot be larger than the value of max_limit
+                      in the [api] section of the ironic configuration, or only
+                      max_limit resources will be returned.
         :param sort_key: column to sort results by. Default: id.
         :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
         :param fields: Optional, a list with a specified set of fields
@@ -216,6 +219,9 @@ class ChassisController(rest.RestController):
 
         :param marker: pagination marker for large data sets.
         :param limit: maximum number of resources to return in a single result.
+                      This value cannot be larger than the value of max_limit
+                      in the [api] section of the ironic configuration, or only
+                      max_limit resources will be returned.
         :param sort_key: column to sort results by. Default: id.
         :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
         """

ironic/api/controllers/v1/node.py

@@ -1119,6 +1119,9 @@ class NodesController(rest.RestController):
                                 that provision state.
         :param marker: pagination marker for large data sets.
         :param limit: maximum number of resources to return in a single result.
+                      This value cannot be larger than the value of max_limit
+                      in the [api] section of the ironic configuration, or only
+                      max_limit resources will be returned.
         :param sort_key: column to sort results by. Default: id.
         :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
         :param driver: Optional string value to get only nodes using that
@@ -1159,6 +1162,9 @@ class NodesController(rest.RestController):
                                 that provision state.
         :param marker: pagination marker for large data sets.
         :param limit: maximum number of resources to return in a single result.
+                      This value cannot be larger than the value of max_limit
+                      in the [api] section of the ironic configuration, or only
+                      max_limit resources will be returned.
         :param sort_key: column to sort results by. Default: id.
         :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
         :param driver: Optional string value to get only nodes using that

ironic/api/controllers/v1/port.py

@@ -264,6 +264,9 @@ class PortsController(rest.RestController):
                         this MAC address.
         :param marker: pagination marker for large data sets.
         :param limit: maximum number of resources to return in a single result.
+                      This value cannot be larger than the value of max_limit
+                      in the [api] section of the ironic configuration, or only
+                      max_limit resources will be returned.
         :param sort_key: column to sort results by. Default: id.
         :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
         :param fields: Optional, a list with a specified set of fields
@@ -303,6 +306,9 @@ class PortsController(rest.RestController):
                         this MAC address.
         :param marker: pagination marker for large data sets.
         :param limit: maximum number of resources to return in a single result.
+                      This value cannot be larger than the value of max_limit
+                      in the [api] section of the ironic configuration, or only
+                      max_limit resources will be returned.
         :param sort_key: column to sort results by. Default: id.
         :param sort_dir: direction to sort. "asc" or "desc". Default: asc.
         """