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

  Options:

• scheme

  The scheme to use.

  Type: anyOf

  Options:

• hostname

  The host to connect to.

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

  Type: anyOf

  Options:

• port

  The port to connect to.

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

  Type: anyOf

  Options:

• base_path

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

  Type: anyOf

  Options:

• path

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

  Type: anyOf

  Options:

• method

  The HTTP method to use.

  Type: anyOf

  Options:

• 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

  Options:

• 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

  Options:

  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

  Options:

• 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

  Items:

  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

  Options:

• dst

  Where to store the response.

  Type: anyOf

  Options:

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

• 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

  Options:

  Default: Header list

• cookies

  Cookies which were retrieved with the HTTP response.

  Type: object

  Additional Properties: True

  Pattern Properties:

  • .*

    Type: object

    Properties:

    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

  Items:

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