rest_client Module

Liviu Chircu

OpenSIPS Solutions

Edited by

Liviu Chircu

Revision History
Revision $Revision$$Date$

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. curl_timeout (integer)
1.3.3. ssl_verifypeer (integer)
1.3.4. ssl_verifyhost (integer)
1.3.5. 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.5. Exported Asyncronous Functions
1.5.1. rest_get(url, body_pv[, ctype_pv[, retcode_pv]])

List of Examples

1.1. Setting the connection_timeout parameter
1.2. Setting the curl_timeout parameter
1.3. Setting the ssl_verifypeer parameter
1.4. Setting the ssl_verifyhost parameter
1.5. Setting the ssl_capath parameter
1.6. rest_get usage
1.7. rest_post usage
1.8. async rest_post usage

Chapter 1. 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.

Example 1.1. Setting the connection_timeout parameter

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

1.3.2. curl_timeout (integer)

Maximum time allowed for the libcurl transfer to complete.

Default value is “20” seconds.

Example 1.2. Setting the curl_timeout parameter

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

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

Example 1.3. Setting the ssl_verifypeer parameter

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

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

Example 1.4. Setting the ssl_verifyhost parameter

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

1.3.5. ssl_capath (integer)

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

Example 1.5. 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.

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.6. rest_get usage

...
# Example of querying a REST service to get the credit of an account

if (!rest_get("http://getcredit.org/?ruri=$fU", "$var(credit)", "$var(ct)", "$var(rcode)")) {
	xlog("Error code $var(rcode) in HTTP GET!\n");
	send_reply("403", "Not registered");
	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. Its MIME content type will be taken from 'send_ctype_pv'.

The 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 save the HTTP status code of the response message.

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.7. rest_post usage

...
# Storing data using a RESTful service with an HTTP POST request

if (!rest_post("http://myserver.org/register_user", "$fU", "text/plain", "$var(body)", "$var(ct)", "$var(rcode)")) {
	xlog("Error code $var(rcode) in HTTP POST!\n");
	send_reply("403", "POST Forbidden");
	exit;
}
...

1.5. Exported Asyncronous Functions

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

Runs a GET HTTP requests. This function does exactly the same as Section 1.4.1, “ rest_get(url, body_pv[, ctype_pv[, retcode_pv]]) (in terms of input, output and processing), but in an asynchronous way. The script execution is suspended until the HTTP response if available for read (the full response).

Example 1.8. async rest_post usage

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

route[resume] {
	if ( $rc < 0 ) {
		xlog("Error code $var(rcode) in HTTP POST!\n");
		send_reply("403", "POST Forbidden");
		exit;
	}
	......
}