Skip to main content
Version: 6 - Palatschinke

ConnectorTypeREST

class connector_types.connector_type_rest.ConnectorTypeREST

Call a REST service.

Inputs

NameTypeDefaultDescription
allow_redirectsboolTrueIf set to False do not follow redirects. True by default.
authentication_methodstrNoneMode used for authentication, currently only supports basic.
base_pathstrNoneA part of the path. The full path will be [base path]/[path].
cacertstrNoneTo 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_timeoutfloatNoneA timeout in seconds for connecting to a peer. Can be disabled by setting to 0 or None
cookiesdictNone
dataobjectsentinel.NotSetDEPRECATED: a JSON body
dststrNoneSet to a name of a Cloudomation file to store the reponse body.
expected_status_codelist[200, 201, 202, 204]HTTP status codes which result in ENDED_SUCCESS. All other HTTP status codes will result in ENDED_ERROR.
grantstrNoneThe name of an oauth grant to use for authentication
headersdictNone
hostnamestrNoneThe host to connect to. Either url or hostname must be set. When both are specified, url takes precedence.
jsonobjectsentinel.NotSetA JSON body. Only allowed for the methods post, put, patch, and delete.
max_redirectsint10Maximum number of redirects to follow. 10 by default.
methodstrNone
multipartdictNoneA multipart body
paramsdictNoneQuery string parameters. Will be urlencoded automatically
passwordstrNonePassword used for basic authentication.
pathstrNoneA part of the path. The full path will be [base path]/[path].
portintNoneThe port to connect to. Defaults to 443 when using the "https" scheme, defaults to 80 when using the "http" scheme.
read_timeoutfloatNoneA timeout in seconds for reading a portion of data from a peer. Can be disabled by setting to 0 or None
retry_backoffdict{'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_codelist[502, 503, 504]HTTP status codes on which a retry is performed
schemestrhttpsThe scheme to use. Currently supported are "http" and "https" (default)
textstrNoneA text body
total_timeoutfloatNoneTotal timeout in seconds for the whole request. Can be disabled by setting to 0 or None
urlstrNoneThe URL to connect to. Use the format [scheme]://[hostname]/[path]. Either url or hostname must be set. When both are specified, url takes precedence.
urlencodeddictNoneA dictionary, with key-value pairs, which are to be sent as urlencoded request.
usernamestrNoneUsername used for basic authentication.
verify_sslboolTruePerform validation of ssl certificates. This can be disabled to use self-signed certificates where the cacert is not available.

Outputs

NameTypeDefaultDescription
bytesstrThe base64 encoded binary response body. Will only be set if the body cannot be represented as text or json.
cookiesdict
encodingstr
execution_idintThe ID of the connection execution
headersdict
jsonobjectThe response body. Will only be set if it can be represented as text and json.
loglist
messagestrThe ended message for the connection. If the connection ended with an error, the message will contain information about what went wrong
statusstrThe ended status for the connection. Either "success" or "error".
status_codeint
textstrThe 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

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