ConnectorTypeREST

class connector_types.connector_type_rest.ConnectorTypeREST

Call a REST service.

Inputs

Name	Type	Default	Description
allow_redirects	bool	True	If set to False do not follow redirects. True by default.
authentication_method	str	None	Mode used for authentication, currently only supports basic.
base_path	str	None	A part of the path. The full path will be [base path]/[path].
cacert	str	None	To attach self-signed certificates (ca = certificate authority, cert = certificate) To access https:// urls, you need to sign your request. Certificates trusted by default by debian jessie will work. To disable certificate verification set verify_ssl to False.
connect_timeout	float	None	A timeout in seconds for connecting to a peer. Can be disabled by setting to 0 or None
cookies	dict	None
data	object	sentinel.NotSet	DEPRECATED: a JSON body
dst	str	None	Set to a name of a Cloudomation file to store the reponse body.
expected_status_code	list	[200, 201, 202, 204]	HTTP status codes which result in ENDED_SUCCESS. All other HTTP status codes will result in ENDED_ERROR.
grant	str	None	The name of an oauth grant to use for authentication
headers	dict	None
hostname	str	None	The host to connect to. Either url or hostname must be set. When both are specified, url takes precedence.
json	object	sentinel.NotSet	A JSON body. Only allowed for the methods post, put, patch, and delete.
max_redirects	int	10	Maximum number of redirects to follow. 10 by default.
method	str	None
multipart	dict	None	A multipart body
params	dict	None	Query string parameters. Will be urlencoded automatically
password	str	None	Password used for basic authentication.
path	str	None	A part of the path. The full path will be [base path]/[path].
port	int	None	The port to connect to. Defaults to 443 when using the "https" scheme, defaults to 80 when using the "http" scheme.
read_timeout	float	None	A timeout in seconds for reading a portion of data from a peer. Can be disabled by setting to 0 or None
retry_backoff	dict	{'initial': 1, 'maximum': 60, 'multiplier': 2, 'deadline': 600}	Configration of retries. Possible keys: - initial: float - how many seconds to wait before the first retry. - maximum: float - maximum seconds to wait between retries. - multiplier: float - the delay between each retry is multiplied by this value. - deadline: float - after how many seconds of retrying to stop and fail. the minimum delay between two tries is 1 second.
retry_status_code	list	[502, 503, 504]	HTTP status codes on which a retry is performed
scheme	str	https	The scheme to use. Currently supported are "http" and "https" (default)
text	str	None	A text body
total_timeout	float	None	Total timeout in seconds for the whole request. Can be disabled by setting to 0 or None
url	str	None	The URL to connect to. Use the format [scheme]://[hostname]/[path]. Either url or hostname must be set. When both are specified, url takes precedence.
urlencoded	dict	None	A dictionary, with key-value pairs, which are to be sent as urlencoded request.
username	str	None	Username used for basic authentication.
verify_ssl	bool	True	Perform validation of ssl certificates. This can be disabled to use self-signed certificates where the cacert is not available.

Outputs

Name	Type	Default	Description
bytes	str		The base64 encoded binary response body. Will only be set if the body cannot be represented as text or json.
cookies	dict
encoding	str
execution_id	int		The ID of the connection execution
headers	dict
json	object		The response body. Will only be set if it can be represented as text and json.
log	list
message	str		The ended message for the connection. If the connection ended with an error, the message will contain information about what went wrong
status	str		The ended status for the connection. Either "success" or "error".
status_code	int
text	str		The response body. Will only be set if it can be represented as text, but it cannot be represented as json.

Constants

input_list = ['allow_redirects', 'authentication_method', 'base_path', 'cacert', 'connect_timeout', 'cookies', 'data', 'dst', 'expected_status_code', 'grant', 'headers', 'hostname', 'json', 'max_redirects', 'method', 'multipart', 'params', 'password', 'path', 'port', 'read_timeout', 'retry_backoff', 'retry_status_code', 'scheme', 'text', 'total_timeout', 'url', 'urlencoded', 'username', 'verify_ssl'] output_list = ['bytes', 'cookies', 'encoding', 'headers', 'json', 'log', 'status_code', 'text'] ssl_context_inputs = ['check_hostname', 'client_cert', 'client_key', 'server_ca'] version = 1

Methods

execute ()

log (message)

one_of_inputs (options)

run ()

Example

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution):
    # create a REST connection and run it
    child_execution = this.connect(
        connector_type='REST',
        url='https://api.jokes.one/jod',
    )
    # access a field of the JSON response
    joke = child_execution.get('output_value')['json']['contents']['jokes'][0]['joke']['text']
    # end with a joke
    return this.success(message=joke)

More

Specify parts of URL

Alternatively to specifying the full URL it is possible to specify different parts of the URL separately:

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution):
    # the resulting URL will be
    # https://httpbin.org/anything/some/path?query=parameter
    this.connect(
        connector_type='REST',
        scheme='https', # defaults to https
        hostname='httpbin.org',
        base_path='anything',
        path='some/path',
        params={
            'query': 'parameter',
        },
    )
    return this.success('all done')

Sending multipart POST requests

The Cloudomation REST connector can be used to upload files using a multipart POST request. Here are some usage examples:

Basic example

Specify a value in the part for a string payload, or specify a file in the part to upload a file from the Cloudomation files resource.

this.connect(
    connector_type='REST',
    url='https://httpbin.org/post',
    method='POST',
    multipart={
        'parts': [
            {
                'name': 'string-field',
                'value': 'spam & eggs',
            },
            {
                'name': 'file',
                'file': 'report.txt',
            },
        ],
    },
)

The example above will generate the following request:

Content-Length: '991'
Content-Type: multipart/mixed; boundary=aec30e9afc384303b6cb67e44aaa0f9c

--aec30e9afc384303b6cb67e44aaa0f9c
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name="string-field"
Content-Length: 11

spam & eggs
--aec30e9afc384303b6cb67e44aaa0f9c
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name="file"; filename="report.txt"
Content-Length: 608

...content of the report.txt file...
--aec30e9afc384303b6cb67e44aaa0f9c--

Full example

It is possible to modifiy the request being generated.

• Specify a custom content-type or boundary in the multipart dictionary to override the default values.
• Specify a custom content-type, content-disposition, or content-length in the part dictionary to override the default values.
• Specify False for content-type, content-disposition, or content-length in the part dictionary to omit the field in the request.

this.connect(
    connector_type='REST',
    url='https://httpbin.org/post',
    method='POST',
    multipart={
        'content-type': 'application/my-custom-content-type',
        'boundary': 'my-custom-boundary',
        'parts': [
            {
                'name': 'string-field',
                'value': '<pre>spam & eggs</pre>',
                'content-type': 'text/html',
                'content-disposition': False,
                'content-length': False,
            },
            {
                'name': 'file',
                'file': 'report.txt',
                'content-disposition': 'form-data; filename="report.txt"',
            },
        ],
    },
)

The example above will generate the following request:

Content-Length: '848'
Content-Type: application/my-custom-content-type; boundary=my-custom-boundary

--my-custom-boundary
Content-Type: text/html

<pre>spam & eggs</pre>
--my-custom-boundary
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; filename="report.txt"
Content-Length: 608

...content of the report.txt file...
--my-custom-boundary--