ConnectorTypeREST

class connector_types.connector_type_rest.ConnectorTypeREST

Call a REST service.

Input Schema

• schema_version

  Type: string

• authentication

  Type: anyOf

  Options:

• scheme

  The scheme to use.

  Type: anyOf

  Options:

• host

  The remote hostname or IP address.

  Type: string

• port

  Type: anyOf

  Options:

• base_path

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

  Type: string

• path

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

  Type: string

• mode

  Type: anyOf

  Options:

• query

  Will be urlencoded automatically

  Type: array

  Items:

• headers

  Headers to send with the request.

  Type: array

  Items:

• cookies

  Cookies to send with the request.

  Type: object

  Additional Properties: {'element': 'form-string', 'type': 'string', 'label': 'Value', 'default': ''}

• tls

  If to connect using TLS/SSL.

  Type: anyOf

  Options:

• 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 True redirects are followed and the response of the last non-redirect request is returned.

  If set to False redirects are not followed and the response of the first request is returned.

  Type: boolean

  Default: True

• max_redirects

  Maximum number of redirects to follow.

  Type: integer

  Default: 10

• total_timeout

  Total timeout for the request in seconds.

  Type: integer

  Default: 30

• connect_timeout

  A timeout for connecting to a peer in seconds.

  Type: integer

  Default: 30

• read_timeout

  A timeout for reading a portion of data from a peer in seconds.

  Type: integer

  Default: 30

• destination

  Type: anyOf

  Options:

Output Schema

• status_code

  The status code of the HTTP response.

  Type: integer

• headers

  The headers of the HTTP response.

  Type: array

  Items:

• cookies

  Cookies which were retrieved with the HTTP response.

  Type: object

  Additional Properties: True

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

• text

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

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

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',
        **flow_api.split_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

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
        host='httpbin.org',
        base_path='anything',
        path='some/path',
        query=[
            {
                'name': 'some',
                'value': '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',
    **flow_api.split_url('https://httpbin.org/post'),
    mode={
        'mode_name': 'post',
        'body': {
            'body_mode': 'multipart',
            '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',
    **flow_api.split_url('https://httpbin.org/post'),
    mode={
        'mode_name': 'post',
        'body': {
            'body_mode': 'multipart',
            '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--