Table of Contents
List of Examples
connection_timeout parametermax_async_transfers parametercurl_timeout parameterssl_verifypeer parameterssl_verifyhost parameterssl_capath parameterrest_get usagerest_post usageasync rest_get usageasync rest_post usageThe rest_client module provides a means of interacting with an HTTP server by doing RESTful queries, such as GET and POST.
The following modules must be loaded before this module:
No dependencies on other OpenSIPS modules..
Maximum time allowed to establish a connection with the server.
Default value is “20” seconds.
Example 1.1. Setting the connection_timeout parameter
...
modparam("rest_client", "connection_timeout", 300)
...
Maximum number of asynchronous HTTP transfers a single OpenSIPS worker is allowed to run simultanously. 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”.
Example 1.2. Setting the max_async_transfers parameter
...
modparam("rest_client", "max_async_transfers", 300)
...
Maximum time allowed for the libcurl transfer to complete.
Default value is “20” seconds.
Example 1.3. Setting the curl_timeout parameter
...
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).
Example 1.4. Setting the ssl_verifypeer parameter
...
modparam("rest_client", "ssl_verifypeer", 0)
...
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
url - String, pseudo-variable, or a String which includes pseudo-variables. (useful for specifying additional attribute-value fields in the URL)
body_pv, ctype_pv, retcode_pv - pseudo-variables
This function can be used from the startup, branch, failure, request and timer routes.
Example 1.7. rest_get usage
...
# 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")
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 based on libcurl, a 0 value means no HTTP reply arrived at all.
Possible parameter types
url, send_body_pv, send_type_pv - String, pseudo-variable, or a String which includes pseudo-variables.
recv_body_pv, recv_ctype_pv, retcode_pv - pseudo-variables
This function can be used from the startup, branch, failure, request and timer routes.
Example 1.8. rest_post usage
...
# 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;
}
...
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.
Example 1.9. async rest_get usage
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.
Example 1.10. async rest_post usage
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;
}
...
}