rest_client Module

The following modules must be loaded before this module:

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

Maximum time allowed to establish a connection with the server.

Default value is “20” seconds.

...
modparam("rest_client", "connection_timeout", 300)
...

Allows complete control over how quickly we want to detect libcurl's completed TCP handshakes, so the transfers can be started. A lower "connect_poll_interval" will speed up all HTTP transfers, but will also increase CPU usage.

Default value is “20” milliseconds.

...
modparam("rest_client", "connect_poll_interval", 2)
...

Maximum number of asynchronous HTTP transfers a single OpenSIPS worker is allowed to run simultaneously. As long as this threshold is reached for a worker, all new async transfers it attempts to perform will be done in a blocking manner, with appropriate logging warnings.

Default value is “100”.

...
modparam("rest_client", "max_async_transfers", 300)
...

Maximum time allowed for the libcurl transfer to complete.

Default value is “20” seconds.

...
modparam("rest_client", "curl_timeout", 300)
...

Set this to 0 in order to disable the verification of the remote peer's certificate. Verification is done using a default bundle of CA certificates which come with libcurl.

Default value is “1” (enabled).

...
modparam("rest_client", "ssl_verifypeer", 0)
...

Set this to 0 in order to disable the verification that the remote peer actually corresponds to the server listed in the certificate.

Default value is “1” (enabled).

...
modparam("rest_client", "ssl_verifyhost", 0)
...

An optional path for CA certificates to be used for host verifications.

...
modparam("rest_client", "ssl_capath", "/home/opensips/ca_certificates")
...

Issues an HTTP GET request to the given 'url', and returns a representation of the resource.

The body_pv pseudo-var will hold the body of the HTTP response.

The optional ctype_pv pseudo-var will contain the value of the "Content-Type:" header.

The optional retcode_pv pseudo-var is used to retain the HTTP status code of the response message. Since the module is based on libcurl, a 0 value means no HTTP reply arrived at all.

Possible parameter types

This function can be used from the startup, branch, failure, request and timer routes.

...
# Example of querying a REST service to get the credit of an account
$var(rc) = rest_get("http://getcredit.org/?account=$fU", "$var(credit)", "$var(ct)", "$var(rcode)");

if ($var(rc) < 0) {
	xlog("rest_get() failed with $var(rc), acc=$fU\n");
	send_reply("500", "Server Internal Error");
	exit;
}
if ($var(rcode) >= 300) {
	xlog("L_INFO", "rest_get() rcode=$var(rcode), acc=$fU\n");
	send_reply("403", "Forbidden");
	exit;
}
...

Issues an HTTP POST request to the specified url. The request body will be copied from the send_body_pv pseudo-variable. The MIME Content-Type header for the request will be taken from send_ctype_pv (default is "application/x-www-form-urlencoded")

Note that the send_body_pv parameter can also accept a format-string but it cannot be larger than 1024 bytes. For bigger messages, you must build them in a pseudo-variable and pass it to the function.

The mandatory recv_body_pv pseudo-var will hold the body of the HTTP response.

The optional recv_ctype_pv parameter will contain the value of the "Content-Type" header of the response message.

The optional retcode_pv pseudo-var parameter can be given in order to retrieve the HTTP status code of the response message. Since the module is based on libcurl, a 0 value means no HTTP reply arrived at all.

Possible parameter types

This function can be used from the startup, branch, failure, request and timer routes.

...
# Creating a resource using a RESTful service with an HTTP POST request
$var(rc) = rest_post("http://myserver.org/register_user", "$fU", , "$var(body)", "$var(ct)", "$var(rcode)");

if ($var(rc) < 0) {
	xlog("rest_post() failed with $var(rc), user=$fU\n");
	send_reply("500", "Server Internal Error 1");
	exit;
}
if ($var(rcode) >= 300) {
	xlog("rest_post() rcode=$var(rcode), user=$fU\n");
	send_reply("500", "Server Internal Error 2");
	exit;
}
...

Issues an HTTP PUT request to the specified url. The request body will be copied from the send_body_pv pseudo-variable. The MIME Content-Type header for the request will be taken from send_ctype_pv (default is "application/x-www-form-urlencoded")

Similar to the rest_post, the send_body_pv parameter can also accept a format-string but it cannot be larger than 1024 bytes. For bigger messages, you must build them in a pseudo-variable and pass it to the function.

The mandatory recv_body_pv pseudo-var will hold the body of the HTTP response.

The optional recv_ctype_pv parameter will contain the value of the "Content-Type" header of the response message.

The optional retcode_pv pseudo-var parameter can be given in order to retrieve the HTTP status code of the response message. Since the module is based on libcurl, a 0 value means no HTTP reply arrived at all.

Possible parameter types

This function can be used from the startup, branch, failure, request and timer routes.

...
# Creating/Updating a resource using a RESTful service with an HTTP PUT request
$var(rc) = rest_put("http://myserver.org/users/$fU", "$var(userinfo)", , "$var(body)", "$var(ct)", "$var(rcode)");

if ($var(rc) < 0) {
	xlog("rest_put() failed with $var(rc), user=$fU\n");
	send_reply("500", "Server Internal Error 3");
	exit;
}
if ($var(rcode) >= 300) {
	xlog("rest_put() rcode=$var(rcode), user=$fU\n");
	send_reply("500", "Server Internal Error 4");
	exit;
}
...

Appends 'txt' to the HTTP headers of the subsequent request. Multiple headers can be appended by making multiple calls before executing a request.

The contents of txt should adhere to the specification for HTTP headers (ex. Field: Value)

Parameter types

This function can be used from the startup, branch, failure, request and timer routes.

...
# Example of querying a REST service requiring additional headers

rest_append_hf("Authorization: Bearer mF_9.B5f-4.1JqM");
$var(rc) = rest_get("http://getcredit.org/?account=$fU", "$var(credit)");
...
		

Sends a GET HTTP request. This function behaves exactly the same as rest_get (in terms of input, output and processing), but in an asynchronous way. Script execution is suspended until the entire content of the HTTP response is available.

route {
	...
	async(rest_get("http://getcredit.org/?account=$fU", "$var(credit)", , "$var(rcode)"), resume);
}

route [resume] {
	$var(rc) = $rc;
	if ($var(rc) < 0) {
		xlog("async rest_get() failed with $var(rc), acc=$fU\n");
		send_reply("500", "Server Internal Error");
		exit;
	}

	if ($var(rcode) >= 300) {
		xlog("L_INFO", "async rest_get() rcode=$var(rcode), acc=$fU\n");
		send_reply("403", "Forbidden");
		exit;
	}

	...
}

Sends a POST HTTP request. This function behaves exactly the same as rest_post (in terms of input, output and processing), but in an asynchronous way. Script execution is suspended until the entire content of the HTTP response is available.

route {
	...
	async(rest_post("http://myserver.org/register_user", "$fU", , "$var(body)", "$var(ct)", "$var(rcode)"), resume);
}

route [resume] {
	$var(rc) = $rc;
	if ($var(rc) < 0) {
		xlog("async rest_post() failed with $var(rc), user=$fU\n");
		send_reply("500", "Server Internal Error 1");
		exit;
	}
	if ($var(rcode) >= 300) {
		xlog("async rest_post() rcode=$var(rcode), user=$fU\n");
		send_reply("500", "Server Internal Error 2");
		exit;
	}

	...
}

Sends a PUT HTTP request. This function behaves exactly the same as rest_put (in terms of input, output and processing), but in an asynchronous way. Script execution is suspended until the entire content of the HTTP response is available.

route {
	...
	async(rest_put("http://myserver.org/users/$fU", "$var(userinfo)", , "$var(body)", "$var(ct)", "$var(rcode)"), resume);
}

route [resume] {
	$var(rc) = $rc;
	if ($var(rc) < 0) {
		xlog("async rest_put() failed with $var(rc), user=$fU\n");
		send_reply("500", "Server Internal Error 3");
		exit;
	}
	if ($var(rcode) >= 300) {
		xlog("async rest_put() rcode=$var(rcode), user=$fU\n");
		send_reply("500", "Server Internal Error 4");
		exit;
	}

	...
}