QueryREST

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

Added in version 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

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

Warning

Deprecated. execute() logs a warning directing you to GetREST, PostREST or DeleteREST. Documented for the benefit of workflows that still use it — see Deprecated steps.

Behaviour

Unlike the current REST steps, this one does not extend Shared parameters: HTTPBaseStep. It extends BaseStep directly and declares its own full parameter set, which is why its table above duplicates names you will also find on the shared HTTP page. The two sets are not interchangeable.

The practical consequence: authentication is limited to HTTP Basic. There is no OAuth, no bearer token and no mTLS on this step. Those are the reasons to move off it.

Outputs

save_data_for_next_step(all_data), which is one of:

  • a list of row dicts extracted from result_key, paged for chunked GETs;

  • a plain list, when the response is already a list;

  • the full response dict, when the structure does not match result_key.

On error it saves {"http_code": ..., "headers": ..., "body": ...} before raising.

Notes

  • chunk_name_for_pos_in_url and chunk_name_for_max_in_url are declared as number parameters here, even though the values are URL parameter names. The equivalents on Shared parameters: HTTPBaseStep are strings.

  • object_type has no analogue on the modern steps; it is stored under the platform’s OBJECT_TYPE_KEY.

  • query_retries retries when the status code differs from expected_http_response, so it does nothing unless that is also set.

API

class base_steps_syncpack.steps.QueryREST.QueryREST

Bases: BaseStep

execute()

Main Query rest logic

Returns:

query_with_url_and_payload_from_input()

Attempts to query with the url and payload from the previous step input. This will really only work if the payload and url are using variable substitution.

Returns:

query_with_url_generated_from_input()

Iterates over data from previous steps, and generates a relative url for each. Then executes that command.

Returns:

query_with_payload_from_input()

Performs the specified rest query with the specific payload coming in from user.

Returns:

make_rest_call(request_func, url, headers, out_payload, verify=False, basic_auth=None, allow_redirects=True, stream=False, expected_http_response=None, connect_timeout=20, read_timeout=20, max_retry_attempts=0)

Method which will retry a REST request until it is successful, or until it has failed 5 times. On a successful query, it will return the response. If there’s any failure (unexpected status code, requests exception, max retries, etc) A StepFailedException will be raised.

Parameters:

  • request_func – REST method to execute

  • url – URL to query

  • headers – headers

  • out_payload – data for request

  • verify – whether to verify

  • basic_auth – authentication for request

  • allow_redirects – allow_redirects for requests module

  • stream – stream option from requests module

  • expected_http_response – expected http response for validation

  • connect_timeout – number of seconds to wait for the remote server to provide a response before raising exception

  • read_timeout – number of seconds to wait for the remote server to reply.

  • max_retry_attempts – how many times the call can be retried

Return response:

the Request response