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_put(url, send_body_pv, [send_ctype_pv],
                      recv_body_pv[, [recv_ctype_pv][,
                      [retcode_pv]]])

              1.4.4. rest_append_hf(txt)
              1.4.5. rest_init_client_tls(tls_client_domain)

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

              1.5.3. rest_put(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_put usage
   1.11. rest_append_hf usage
   1.12. rest_init_client_tls usage
   1.13. async rest_get usage
   1.14. async rest_post usage
   1.15. async rest_put 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,PUT 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. 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.

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

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

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

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

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

   Example 1.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 any route.

   Example 1.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")

   Note that 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 any route.

   Example 1.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_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 any route.

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

1.4.4.  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 any route.

   Example 1.11. 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.4.5.  rest_init_client_tls(tls_client_domain)

   Force a specific TLS certificate and private key pair to be
   eventually used during the next request. Refer to the tls_mgm
   module for additional info regarding TLS client domains.

   If using this parameter, you must also ensure that tls_mgm is
   loaded and properly configured.

   Note that if you want to use this feature, the certificate must
   be provisioned in the configuration file, NOT in the database.
   In case you are loading TLS certificates from the database, you
   must at least define the default domain in the configuration
   script, where is currently the only place you can define it.

   Parameter types
     * tls_client_domain - string, pseudo-variable, or a string
       which includes pseudo-variables.

   This function can be used from any route.

   Example 1.12. rest_init_client_tls usage
...
rest_init_client_tls("1=10.11.12.13:3306");
if (!rest_get("https://example.com"))
    xlog("query failed\n");
...

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.

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

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

        ...
}


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

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

        ...
}

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Liviu Chircu (@liviuchircu) 78 48 2440 522
   2. Ionut Ionita (@ionutrazvanionita) 23 12 663 262
   3. Razvan Crainea (@razvancrainea) 9 7 26 11
   4. Bogdan-Andrei Iancu (@bogdan-iancu) 6 4 95 47
   5. Jarrod Baumann (@jarrodb) 6 3 131 32
   6. Agalya Ramachandran (@AgalyaR) 6 2 354 1
   7. Ryan Bullock (@rrb3942) 5 2 91 77
   8. Andrey Vorobiev (@andrey-vorobiev) 2 1 4 0
   9. Vlad Patrascu (@rvlad-patrascu) 2 1 1 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. 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

   Table 2.2. Most recently active contributors^(1) to this module
                     Name                   Commit Activity
   1. Liviu Chircu (@liviuchircu)         Mar 2013 - Aug 2018
   2. Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2014 - Jun 2018
   3. Razvan Crainea (@razvancrainea)     Aug 2015 - Nov 2017
   4. Vlad Patrascu (@rvlad-patrascu)     May 2017 - May 2017
   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

Chapter 3. Documentation

3.1. Contributors

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

   doc copyrights:

   Copyright © 2013 www.opensips-solutions.com
