Skip to main content
Version: 10 - TBD

ConnectorTypeREST

class connector_types.connector_type_rest.ConnectorTypeREST

Call a REST service.

Input Schema

  • url

    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.

    Type: anyOf

  • scheme

    The scheme to use.

    Type: anyOf

  • hostname

    The host to connect to.

    Either url or hostname must be set. When both are specified, url takes precedence.

    Type: anyOf

  • port

    The port to connect to.

    Defaults to 443 when using the "https" scheme, defaults to 80 when using the "http" scheme.

    Type: anyOf

  • base_path

    A part of the path. The full path will be <base path>/<path>.

    Type: anyOf

  • path

    A part of the path. The full path will be <base path>/<path>.

    Type: anyOf

  • method

    The HTTP method to use.

    Type: anyOf

  • params

    Will be urlencoded automatically

    Type: object

    Additional Properties: True

    Pattern Properties:

    • .*

      Value of the parameter

  • body

    A body payload to send with the request. Only allowed for the methods post, put, patch, and delete.

    Type: anyOf

  • text

    DEPRECATED. Replaced by body.text.

  • json

    DEPRECATED. Replaced by body.json.

  • multipart

    DEPRECATED. Replaced by body.multipart.

  • urlencoded

    DEPRECATED. Replaced by body.urlencoded.

  • headers

    Headers to send with the request.

    Type: anyOf

    Default: Header list

  • cookies

    Cookies to send with the request.

    Type: object

    Additional Properties: True

    Pattern Properties:

    • .*

      Type: string

  • cacert

    Use a self-signed certificate to verify the https connection. To disable certificate verification set verify_ssl to False.

    Type: anyOf

  • verify_ssl

    Perform validation of ssl certificates. This can be disabled to use self-signed certificates where the CA certificate is not available.

    Type: boolean

    Default: True

  • expected_status_code

    HTTP status codes which result in ENDED_SUCCESS. All other HTTP status codes will result in ENDED_ERROR.

    Type: array

    Default: [200, 201, 202, 204]

  • allow_redirects

    If set to False do not follow redirects. True by default.

    Type: boolean

    Default: True

  • max_redirects

    Maximum number of redirects to follow. 10 by default.

    Type: integer

    Default: 10

  • total_timeout

    Total timeout in seconds for the whole request. Can be disabled by setting to 0.

    Type: integer

  • connect_timeout

    A timeout in seconds for connecting to a peer. Can be disabled by setting to 0.

    Type: integer

  • read_timeout

    A timeout in seconds for reading a portion of data from a peer. Can be disabled by setting to 0.

    Type: integer

  • authentication

    Type: anyOf

  • dst

    Where to store the response.

    Type: anyOf

  • data

    DEPRECATED. Replaced by body.json.

  • retry_status_code

    DEPRECATED. Not used. Use the retry wrapper instead.

  • retry_backoff

    DEPRECATED. Not used. Use the retry wrapper instead.

  • authentication_method

    DEPRECATED. Replaced by authentication.authentication_method_name.

  • username

    DEPRECATED. Replaced by authentication.username.

  • password

    DEPRECATED. Replaced by authentication.password.

  • grant

    DEPRECATED. Replaced by authentication.grant.

Output Schema

  • status_code

    The status code of the HTTP response.

    Type: integer

  • headers

    The headers of the HTTP response.

    Type: anyOf

    Default: Header list

  • cookies

    Cookies which were retrieved with the HTTP response.

    Type: object

    Additional Properties: True

    Pattern Properties:

    • .*

      Type: object

      Additional Properties: False

  • encoding

    The encoding used in the HTTP response.

    Type: string

  • bytes

    The base64 encoded binary response body. Will only be set if the body cannot be represented as text or json.

    Type: string

  • text

    The response body. Will only be set if it can be represented as text, but it cannot be represented as json.

    Type: string

  • json

    The response body. Will only be set if it can be represented as text and json.

  • history

    The history of all requests made when allow_redirects is set.

    Type: array

Constants

ssl_context_inputs = ['check_hostname', 'client_cert', 'client_key', 'server_ca']

Example

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution, inputs: dict):
# create a REST connection and run it
child_execution = this.connect(
connector_type='REST',
url='https://api.chucknorris.io/jokes/random',
)
# access a field of the JSON response
joke = child_execution.get('output_value')['json']['value']
# 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, inputs: dict):
# 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 Engine 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 Engine 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--