Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

cURL

      +

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

      This feature 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.

      The URL needs to point to a REST endpoint and must be either http:// or https:// only. No other protocol is 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 Eventing Function 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 Eventing Function 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 Function invocation.