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:

The maximum allowed time for any HTTP(S) transfer to complete. This interval is inclusive of the initial connect time window, hence the value of this parameter must be greater than or equal to connection_timeout.

Default value is “20” seconds.

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

The maximum allowed time to establish a connection with the server.

Default value is “20” seconds.

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

Only relevant with async requests. Allows complete control over how quickly we want to detect libcurl's completed blocking TCP/TLS handshakes, so the async transfers can be put in the background. A lower connect_poll_interval may speed up all async 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)
...

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")
...

Include a "Expect: 100-continue" HTTP header field whenever the body size of a POST or PUT request exceeds 1024 bytes. Once enabled, the timeout for waiting for a "100 Continue" reply from the server is 1 second, after which the body upload will begin.

Default value is “false” (disabled).

...
modparam("rest_client", "enable_expect_100", true)
...

Perform a blocking HTTP GET on the given url and return 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 of the response.

The optional retcode_pv pseudo-var will retain the status code of the HTTP response. A 0 status code value means no HTTP reply arrived at all.

Parameter Types

Return Codes

This function can be used from any route.

...
# Example of querying a REST service to get the credit of an account
$var(rc) = rest_get("https://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) != 200) {
	xlog("L_INFO", "rest_get() rcode=$var(rcode), acc=$fU\n");
	send_reply("403", "Forbidden");
	exit;
}
...

Perform a blocking HTTP POST on the given 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 (the 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 larger 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.

The optional retcode_pv pseudo-var will retain the status code of the HTTP response. A 0 status code value means no HTTP reply arrived at all.

Parameter Types

Return Codes

This function can be used from any route.

...
# Creating a resource using a RESTful service with an HTTP POST request
$var(rc) = rest_post("https://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) != 200) {
	xlog("rest_post() rcode=$var(rcode), user=$fU\n");
	send_reply("500", "Server Internal Error 2");
	exit;
}
...

Perform a blocking HTTP PUT on the given 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 (the default is "application/x-www-form-urlencoded")

Similar to rest_post(), the send_body_pv parameter can also accept a format-string but it cannot be larger than 1024 bytes. For larger 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 will retain the status code of the HTTP response. A 0 status code value means no HTTP reply arrived at all.

Parameter Types

Return Codes

This function can be used from any route.

...
# Creating/Updating a resource using a RESTful service with an HTTP PUT request
$var(rc) = rest_put("https://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) != 200) {
	xlog("rest_put() rcode=$var(rcode), user=$fU\n");
	send_reply("500", "Server Internal Error 4");
	exit;
}
...

Append 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 any route.

...
# 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)");
...
		

Force a specific TLS certificate and private key pair to be eventually used during the next request. Refer to the tls_mgm module for additional info regarding TLS client domains.

If using this function, you must also ensure that tls_mgm is loaded and properly configured.

Note that if you want to use this feature, the certificate must be provisioned in the configuration file, NOT in the database. In case you are loading TLS certificates from the database, you must at least define the default domain in the configuration script, where is currently the only place you can define it.

Parameter types

This function can be used from any route.

...
rest_init_client_tls("1=10.11.12.13:3306");
if (!rest_get("https://example.com"))
    xlog("query failed\n");
...
		

Perform an asynchronous HTTP GET. This function behaves exactly the same as rest_get() (in terms of input, output and processing), but in a non-blocking manner. 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) != 200) {
		xlog("L_INFO", "async rest_get() rcode=$var(rcode), acc=$fU\n");
		send_reply("403", "Forbidden");
		exit;
	}

	...
}

Perform an asynchronous HTTP POST. This function behaves exactly the same as rest_post() (in terms of input, output and processing), but in a non-blocking manner. 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) != 200) {
		xlog("async rest_post() rcode=$var(rcode), user=$fU\n");
		send_reply("500", "Server Internal Error 2");
		exit;
	}

	...
}

Perform an asynchronous HTTP PUT. This function behaves exactly the same as rest_put() (in terms of input, output and processing), but in a non-blocking manner. 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) != 200) {
		xlog("async rest_put() rcode=$var(rcode), user=$fU\n");
		send_reply("500", "Server Internal Error 4");
		exit;
	}

	...
}