rest_client Module


Table of Contents

1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. connection_timeout (integer)
1.3.2. connect_poll_interval (integer)
1.3.3. max_async_transfers (integer)
1.3.4. curl_timeout (integer)
1.3.5. ssl_verifypeer (integer)
1.3.6. ssl_verifyhost (integer)
1.3.7. ssl_capath (integer)
1.4. Exported Functions
1.4.1. rest_get(url, body_pv[, [ctype_pv][, [retcode_pv]]])
1.4.2. rest_post(url, send_body_pv, [send_ctype_pv], recv_body_pv[, [recv_ctype_pv][, [retcode_pv]]])
1.4.3. rest_append_hf(txt)
1.5. Exported Asynchronous Functions
1.5.1. rest_get(url, body_pv[, [ctype_pv][, [retcode_pv]]])
1.5.2. rest_post(url, send_body_pv, [send_ctype_pv], recv_body_pv[, [recv_ctype_pv][, [retcode_pv]]])
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

List of Examples

1.1. Setting the connection_timeout parameter
1.2. Setting the connect_poll_interval parameter
1.3. Setting the max_async_transfers parameter
1.4. Setting the curl_timeout parameter
1.5. Setting the ssl_verifypeer parameter
1.6. Setting the ssl_verifyhost parameter
1.7. Setting the ssl_capath parameter
1.8. rest_get usage
1.9. rest_post usage
1.10. rest_append_hf usage
1.11. async rest_get usage
1.12. async rest_post usage

Chapter1.Admin Guide

1.1.Overview

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

1.2.Dependencies

1.2.1.OpenSIPS Modules

The following modules must be loaded before this module:

  • No dependencies on other OpenSIPS modules..

1.2.2.External Libraries or Applications

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

  • libcurl.

1.3.Exported Parameters

1.3.1.connection_timeout (integer)

Maximum time allowed to establish a connection with the server.

Default value is 20 seconds.

Example1.1.Setting the connection_timeout parameter

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

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

Example1.2.Setting the connect_poll_interval parameter

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

1.3.3.max_async_transfers (integer)

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.

Example1.3.Setting the max_async_transfers parameter

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

1.3.4.curl_timeout (integer)

Maximum time allowed for the libcurl transfer to complete.

Default value is 20 seconds.

Example1.4.Setting the curl_timeout parameter

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

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

Example1.5.Setting the ssl_verifypeer parameter

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

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

Example1.6.Setting the ssl_verifyhost parameter

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

1.3.7.ssl_capath (integer)

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

Example1.7.Setting the ssl_capath parameter

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

1.4.Exported Functions

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

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

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

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.

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

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

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

1.5.Exported Asynchronous Functions

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

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

	...
}

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

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

	...
}

Chapter2.Contributors

2.1.By Commit Statistics

Table2.1.Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

NameDevScoreCommitsLines ++Lines --
1. Liviu Chircu (@liviuchircu)61362215388
2. Jarrod Baumann (@jarrodb)6313132
3. Bogdan-Andrei Iancu (@bogdan-iancu)536718
4. Razvan Crainea (@razvancrainea)5388
5. Andrey Vorobiev (@andrey-vorobiev)2130

(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. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

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

2.2.By Commit Activity

Table2.2.Most recently active contributors(1) to this module

NameCommit Activity
1. Liviu Chircu (@liviuchircu)Mar 2013 - Sep 2018
2. Razvan Crainea (@razvancrainea)Aug 2015 - Sep 2018
3. Bogdan-Andrei Iancu (@bogdan-iancu)Oct 2014 - Jun 2018
4. Andrey Vorobiev (@andrey-vorobiev)Feb 2017 - Feb 2017
5. Jarrod Baumann (@jarrodb)Apr 2015 - May 2015

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

Chapter3.Documentation

3.1.Contributors

Last edited by: Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Jarrod Baumann (@jarrodb).

doc copyrights:

Copyright 2013 www.opensips-solutions.com