cURL

Enterprise Edition

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.

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

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)

JS ArrayBuffer

TEXT

(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)

JS String

JSON

application/json

JS Object

JSON

application/json

JS ArrayBuffer

JSON

(disallowed)

JS String

BINARY

UTF-8

application/octet-stream

JS Object

BINARY

(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

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.