# &adminguide;

## Overview

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

## Dependencies

### &osips; Modules

The following modules must be loaded before this module:

- No dependencies on other &osips; modules..

### External Libraries or Applications

The following libraries or applications must be installed before running &osips; 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)
    ...

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

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

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

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

    if (!rest_post("http://myserver.org/register_user", "$fU", , "$var(body)", "$var(ct)", "$var(rcode)")) {
    	xlog("Error code $var(rcode) in HTTP POST!\n");
    	send_reply("403", "POST Forbidden");
    	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");
    if (!rest_get("http://getcredit.org/?ruri=$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 if available.

#### `async rest_get` usage

    route {
    	...
    	async(rest_get("http://getcredit.org/?ruri=$fU", "$var(credit)", , "$var(rcode)"), resume);
    }

    route [resume]
    {
    	if ($rc < 0) {
    		xlog("Error code $var(rcode) in HTTP GET!\n");
    		send_reply("403", "GET 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 if available.

#### `async rest_post` usage

    route {
    	...
    	async(rest_post("http://myserver.org/register_user", "$fU", , "$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;
    	}
    	......
    }