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

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

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