From 8458f9bccffd6ae33693986e28afa5c5dc5f977b Mon Sep 17 00:00:00 2001 From: Mario Villaplana Date: Tue, 5 Jul 2016 21:09:03 +0000 Subject: [PATCH] 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 | 12 +++++++----- ironic/api/controllers/v1/chassis.py | 6 ++++++ ironic/api/controllers/v1/node.py | 6 ++++++ ironic/api/controllers/v1/port.py | 6 ++++++ 4 files changed, 25 insertions(+), 5 deletions(-) diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 20c9192ac5..dde0076983 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -86,11 +86,13 @@ fields: type: array limit: description: | - Requests a page size of items. Returns a number - of items up to a limit value. Use the ``limit`` parameter to make - an initial limited request and use the ID of the last-seen item - from the response as the ``marker`` parameter value in a - subsequent limited request. + Requests a page size of items. Returns a number of items up to a limit + value. Use the ``limit`` parameter to make an initial limited request and + use the ID of the last-seen item from the response as the ``marker`` + parameter value in a subsequent limited request. This value cannot be + 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 diff --git a/ironic/api/controllers/v1/chassis.py b/ironic/api/controllers/v1/chassis.py index 4c5ffe5e3a..090f684ffb 100644 --- a/ironic/api/controllers/v1/chassis.py +++ b/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. """ diff --git a/ironic/api/controllers/v1/node.py b/ironic/api/controllers/v1/node.py index 0be3bb6240..dcb4846f1a 100644 --- a/ironic/api/controllers/v1/node.py +++ b/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 diff --git a/ironic/api/controllers/v1/port.py b/ironic/api/controllers/v1/port.py index e8f3abc14e..baedd156e9 100644 --- a/ironic/api/controllers/v1/port.py +++ b/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. """