A newer version of this documentation is available.

View Latest
    +

    The curl() function provides a way of interacting with external entities via a REST endpoint using HTTP or HTTPS.

    Eventing functions can interact with external systems by using the curl() function to call their REST API. The possibility to interact with external systems opens a lot of new use cases, such as:

    • Propagation of data changes to other systems.

    • Notifying the application about interesting events.

    • Enriching documents with data from external systems.

    • etc…​

    This feature (introduced in 6.5) is both reliable and secure: the cURL calls are limited to a predefined set of URL bindings, and for each binding we can specify authentication, encryption, and certificate validation as necessary.

    A few important aspects related to cURL are listed below:

    • Automatic parsing of common types of data.

    • Automatic marshaling of common types of data.

    • Ability to access HTTP request and response headers.

    • Ability to handle HTTPS connections.

    • Support for session cookies.

    • Multiple authentication types are supported.

    Language Syntax

    To make a cURL call use the below syntax:

    response_object = curl(method, binding, [request_object])

    In the curl syntax:

    • method - The HTTP method of the cURL request. Must be a string having one of the following values: GET | POST | PUT | HEAD | DELETE.

    • binding - The cURL binding that represents the http endpoint URL that will be accessed by this call.

    • request_object - This parameter captures the request and related information. The request_object is a JavaScript object having the following keys:

      • headers - Optional. A JavaScript Object of key-value pairs with key representing the header name and value representing the header content. Both key and value must be strings.

      • body - A JavaScript variable representing the content of the request body. See below for details on how various JavaScript variable types are marshalled to form the HTTP request.

      • encoding - Optional. A directive on how to encode the body. A string having one of following values:

        FORM | JSON | TEXT | BINARY.

      • path - The sub-path the request is made. This must be a string and will be appended to the URL specified on the binding object.

      • params - This must be a JavaScript Object of key-value pairs. Keys must be strings, and values must be either a string, number or boolean. These will be URL encoded as HTTP request parameters and appended to the request URL.

      • Return value (response_object) - The returned value from the cURL call which captures the response of the remote HTTP server to the request made. This is a JavaScript Object containing the following fields:

        • body - A JavaScript variable representing the content of the response body. See below for details on how the response is unmarshalled into various JavaScript variable types.

        • status - The numeric HTTP status code.

        • headers - A JavaScript Object of key-value pairs with key representing the header name and value representing the header content. Both key and value will be strings.

      • Exceptions Thrown - When an unexpected error occurs, a JavaScript exception of type CurlError inheriting from the JavaScript Error class will be thrown.

    Bindings

    To access an HTTP server using cURL, the handler needs to declare a URL binding and pass the alias of the binding to curl() calls. The binding specifies the remote URL to be accessed and all calls made using such a binding are limited to descendants of the URL specified in the binding.

    HTTPS is used when the URL specifies the https:// prefix. Such a link uses https for encryption of contents, and if enabled, verifies the server certificate using the underlying OS support for server certificate verification. Client certificates are not currently supported.

    The binding may also specify the authentication mechanism and credentials to use. Basic, Digest and Bearer authentication methods are supported. It is strongly recommended that when authentication is used, the binding uses only https protocol to ensure credentials are encrypted when transmitted.

    Cookie support may be enabled at binding level if desired when accessing controlled and trusted endpoints.

    eventing curl bindings

    Example

    In the below example, a cURL request is created to the specified binding profile_svc_binding with the sub-URL /person with URL parameters action and id and the body being a JSON object. The response is a JSON object and is seen containing a field profile_id. In this example, the request is automatically encoded as application/json and response is automatically parsed from JSON response, as no explicit encoding is specified.

    var request = {
        path: '/person',
        params: {
            'action': 'create',
            'id': 23012
        },
        body: {
            'name': 'John Smith',
            'age': 25,
            'state': 'CA',
            'country': 'US',
        }
    };
    
    var response = curl('POST', profile_svc_binding, request);
    if (response.status == 200) {
      var profile_id = response.body.profile_id;
      log("Successfully created profile " + profile_id);
    }

    Request marshalling

    JS object passed to the body param Value passed for encoding param Encoding used for request body Content-Type header sent (unless overridden by headers param)

    JS String

    (not specified)

    UTF-8

    text/plain

    JS Object

    (not specified)

    JSON

    application/json

    JS ArrayBuffer

    (not specified)

    Raw Bytes

    application/octet-stream

    JS String

    TEXT

    UTF-8

    text/plain

    JS Object

    TEXT

    (disallowed)

    (disallowed)

    JS ArrayBuffer

    TEXT

    (disallowed)

    (disallowed)

    JS String

    FORM

    URL Encoding

    application/x-www-form-urlencoded

    JS Object

    FORM

    URL Encoding

    application/x-www-form-urlencoded

    JS ArrayBuffer

    FORM

    (disallowed)

    (disallowed)

    JS String

    JSON

    JSON

    application/json

    JS Object

    JSON

    JSON

    application/json

    JS ArrayBuffer

    JSON

    (disallowed)

    (disallowed)

    JS String

    BINARY

    UTF-8

    application/octet-stream

    JS Object

    BINARY

    (disallowed)

    (disallowed)

    JS ArrayBuffer

    BINARY

    Raw Bytes

    application/octet-stream

    Users who wish to utilize custom encoding can do so by specifying an appropriate Content-Type using the headers parameter of the request object and passing the custom encoded object as an ArrayBuffer as the body parameter of the request.

    Response unmarshalling

    Response object from the remote is automatically unmarshalled if the response contains a recognized Content-Type header. The following table identifies the action used to unmarshal responses:

    Content-Type specified by response Unmarshalling action Response body param

    text/plain

    Convert to string as UTF-8

    JS string

    application/json

    JSON.parse()

    JS Object

    application/x-www-form-urlencoded

    decodeURI()

    JS Object or JS String

    application/octet-stream

    Store raw bytes

    JS ArrayBuffer

    (Content-Type not listed above)

    Store raw bytes

    JS ArrayBuffer

    (Content-Type header missing)

    Store raw bytes

    JS ArrayBuffer

    Session handling

    Cookie support is turned off by default on a cURL binding. So, no cookies will be accepted from the remote server. Cookies can be enabled if accessing a controlled and trusted endpoint. If enabled, cookies are accepted and stored in-memory of the worker object, scoped to the binding object.

    Note that eventing utilizes multiple workers and multiple HTTP cURL sessions and so a handler cannot rely on all requests executing on the same HTTP session. It can rely on issued cookies being presented on subsequent requests only within the duration of a single eventing handler invocation.