REST_CLIENT module

Admin Guide

Overview

The rest_client module provides a means of interacting with an HTTP server by doing RESTful queries, such as GET,PUT and POST.

Dependencies

OpenSIPS Modules

The following modules must be loaded before this module:

• No dependencies on other OpenSIPS modules..

External Libraries or Applications

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

• libcurl.

Exported Parameters

connection_timeout (integer)

Maximum time allowed to establish a connection with the server.

Default value is “20” seconds.

Setting the connection_timeout parameter

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

connect_poll_interval (integer)

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.

Setting the connect_poll_interval parameter

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

max_async_transfers (integer)

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

Setting the max_async_transfers parameter

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

curl_timeout (integer)

Maximum time allowed for the libcurl transfer to complete.

Default value is “20” seconds.

Setting the curl_timeout parameter

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

ssl_verifypeer (integer)

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

Setting the ssl_verifypeer parameter

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

ssl_verifyhost (integer)

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

Setting the ssl_verifyhost parameter

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

ssl_capath (integer)

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

Setting the ssl_capath parameter

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

Exported Functions

rest_get(url, body_pv[, [ctype_pv][, [retcode_pv]]])

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.

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;
}
...

rest_post(url, send_body_pv, [send_ctype_pv], recv_body_pv[, [recv_ctype_pv][, [retcode_pv]]])

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

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

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

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;
}
...

rest_put(url, send_body_pv, [send_ctype_pv], recv_body_pv[, [recv_ctype_pv][, [retcode_pv]]])

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

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

rest_put usage

...
# 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;
}
...

rest_append_hf(txt)

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

• txt - String, pseudo-variable, or a String which includes pseudo-variables. (useful for specifying additional attribute-value fields in the URL)

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

rest_append_hf usage

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

Exported Asynchronous Functions

rest_get(url, body_pv[, [ctype_pv][, [retcode_pv]]])

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.

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;
  }

  ...
}

rest_post(url, send_body_pv, [send_ctype_pv], recv_body_pv[, [recv_ctype_pv][, [retcode_pv]]])

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.

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;
  }

  ...
}

rest_put(url, send_body_pv, [send_ctype_pv], recv_body_pv[, [recv_ctype_pv][, [retcode_pv]]])

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.

async rest_put usage

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;
  }

  ...
}

doc copyrights:

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Liviu Chircu (@liviuchircu)	75	41	2536	688
2.	Ionut Ionita (@ionutrazvanionita)	23	12	668	267
3.	Stefan Darius (@dariusstefan)	11	4	551	75
4.	Razvan Crainea (@razvancrainea)	9	7	27	14
5.	Bogdan-Andrei Iancu (@bogdan-iancu)	6	4	101	53
6.	Jarrod Baumann (@jarrodb)	6	3	136	37
7.	Agalya Ramachandran (@AgalyaR)	6	2	357	4
8.	Ryan Bullock (@rrb3942)	5	2	97	83
9.	Andrey Vorobiev (@andrey-vorobiev)	2	1	4	0

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits

(3) ignoring whitespace edits, renamed files and auto-generated files

By Commit Activity

#	Name	Commit Activity
1.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
2.	Razvan Crainea (@razvancrainea)	Aug 2015 - Jun 2026
3.	Liviu Chircu (@liviuchircu)	Mar 2013 - Sep 2018
4.	Bogdan-Andrei Iancu (@bogdan-iancu)	Oct 2014 - Jun 2018
5.	Ionut Ionita (@ionutrazvanionita)	Feb 2017 - Mar 2017
6.	Andrey Vorobiev (@andrey-vorobiev)	Feb 2017 - Feb 2017
7.	Ryan Bullock (@rrb3942)	Jan 2017 - Jan 2017
8.	Agalya Ramachandran (@AgalyaR)	Oct 2016 - Oct 2016
9.	Jarrod Baumann (@jarrodb)	Apr 2015 - May 2015

(1) including any documentation-related commits, excluding merge commits

Documentation

Contributors

Last edited by: Razvan Crainea (@razvancrainea), Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Agalya Ramachandran (@AgalyaR), Jarrod Baumann (@jarrodb).

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0