.. _step-QueryREST:


QueryREST
=========

Step facilitates REST interactions and will return the returned data dictionary and specified headers as data to the next step

.. versionadded:: 1.0.0

* **Friendly name:** ``Deprecated: Query REST``
* **Step class:** ``base_steps_syncpack.steps.QueryREST.QueryREST``
* **Step version:** ``1.2.7``
* **Required parameters:** ``method``, ``prefix_url``

Parameters
----------

.. list-table::
   :header-rows: 1
   :widths: 22 16 8 16 38

   * - Name
     - Type
     - Required
     - Default
     - Description
   * - ``query_retries``
     - number
     - no
     - ``0``
     - QueryREST specific retry setting. If the query fails with a different status code than expected, dictates how many times the query will be retried.
   * - ``method``
     - enum
     - yes
     - --
     - HTTP method to perform Example: ``GET``
   * - ``prefix_url``
     - string
     - yes
     - --
     - used with relative_url to create the full URL. Example: ``http://host.example.com``
   * - ``username``
     - string
     - no
     - --
     - the REST username Example: ``em7admin``
   * - ``password``
     - string
     - no
     - --
     - the REST password Example: ``em7admin``
   * - ``expected_http_response``
     - number
     - no
     - --
     - If this has a constant response, what you expect it to be. Example: ``200``
   * - ``headers``
     - json
     - no
     - ``{'content-type': 'application/json', 'accept': 'application/json'}``
     - Header dictionary for the REST command. Example: ``{'content-type': 'application/json'}``
   * - ``payload_from_input``
     - boolean
     - no
     - ``False``
     - If true, use the input data as payload for executing the HTTP method.
   * - ``payload``
     - json
     - no
     - --
     - the payload for a POST command. Example: ``{'payload_key': 'payload_value'}``
   * - ``chunk_size``
     - number
     - no
     - ``1000``
     - The max number of records to fetch in one REST call.
   * - ``chunk_name_for_pos_in_url``
     - number
     - no
     - --
     - The value that is specified in the url to indicate where to start grabbing data. For example: ?offset=50. Example: ``offset``
   * - ``chunk_name_for_max_in_url``
     - number
     - no
     - ``1000``
     - The value that is specified in the url to indicate the max number of records to return in this REST call. For example: ?limit=1000. Example: ``limit``
   * - ``chunk_name_for_returned``
     - string
     - no
     - ``total_returned``
     - If the data is set in chunks, the field name in the response that indicates how many rows were returned.
   * - ``chunk_name_for_total``
     - string
     - no
     - ``total_matched``
     - If the data is set in chunks, the field name in the response that indicates how many total rows for this object.
   * - ``result_key``
     - string
     - no
     - ``result_set``
     - The field in the response that contains the data for the arrays of rows returned.
   * - ``object_type``
     - string
     - no
     - --
     - The type of object this is (device, ticket, etc.). This value is stored in the object under the key OBJECT_TYPE_KEY. Example: ``device``
   * - ``headers_to_capture``
     - array of strings
     - no
     - --
     - An array of names from the header to capture in the output. Example: ``['header1', 'header2']``
   * - ``relative_url``
     - string
     - no
     - --
     - The URL suffix Example: ``/api/devices``
   * - ``debug_packet``
     - boolean
     - no
     - ``False``
     - Set to to see some special/extra debug messages Example: ``True``
   * - ``url_from_input``
     - boolean
     - no
     - ``False``
     - Set this to perform a rest query to a URI generated from input data from each element in the input_data. The input variables can be referenced from the relative_url parameter, but not prefix_url
   * - ``connect_timeout``
     - number
     - no
     - ``20``
     - Time in seconds to wait for HTTP Connect Response.
   * - ``read_timeout``
     - number
     - no
     - ``20``
     - Time in seconds to wait for HTTP Read Response.

Every step also accepts the platform parameters common to all steps --
see :ref:`platform-parameters`.

Dependencies
------------

* **Inherits from:** ``QueryREST`` -> ``BaseStep`` -> ``Serializable``
* **SyncPack modules:** ``base_steps_syncpack.util.status_code_errors``
* **External packages:** ``future``, ``ipaascommon``, ``ipaascore``, ``requests``, ``requests_oauthlib``, ``six``, ``urllib3``

.. include:: /_step_notes/QueryREST.rst

API
---

.. autoclass:: base_steps_syncpack.steps.QueryREST.QueryREST
   :members:
   :show-inheritance: