cURL

The curl() function provides a way of interacting with external entities using HTTP.

Eventing functions can interact with external systems by using 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, and so on. This feature (introduced in 6.5) is both reliable and secure: the cURL calls are limited to a predefined set of URL bindings, 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

  • Additional authentication types 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.

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