Skip to content

Commit

Permalink
rest_client: Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@liviuchircu
liviuchircu committed Mar 28, 2018
1 parent aa7bfeb commit e004450
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 21 deletions.
54 changes: 40 additions & 14 deletions modules/rest_client/README
View file
Expand Up @@ -48,6 +48,7 @@ Liviu Chircu
[retcode_pv]]])

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

1.5. Exported Asynchronous Functions

Expand Down Expand Up @@ -75,9 +76,10 @@ Liviu Chircu
1.9. rest_post usage
1.10. rest_put usage
1.11. rest_append_hf usage
1.12. async rest_get usage
1.13. async rest_post usage
1.14. async rest_put 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

Expand Down Expand Up @@ -210,8 +212,7 @@ modparam("rest_client", "ssl_capath", "/home/opensips/ca_certificates")
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.
This function can be used from any route.

Example 1.8. rest_get usage
...
Expand Down Expand Up @@ -260,8 +261,7 @@ if ($var(rcode) >= 300) {
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.
This function can be used from any route.

Example 1.9. rest_post usage
...
Expand Down Expand Up @@ -311,8 +311,7 @@ if ($var(rcode) >= 300) {
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.
This function can be used from any route.

Example 1.10. rest_put usage
...
Expand Down Expand Up @@ -347,8 +346,7 @@ if ($var(rcode) >= 300) {
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.
This function can be used from any route.

Example 1.11. rest_append_hf usage
...
Expand All @@ -359,6 +357,34 @@ $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]]])
Expand All @@ -368,7 +394,7 @@ $var(rc) = rest_get("http://getcredit.org/?account=$fU", "$var(credit)")
but in an asynchronous way. Script execution is suspended until
the entire content of the HTTP response is available.

Example 1.12. async rest_get usage
Example 1.13. async rest_get usage
route {
...
async(rest_get("http://getcredit.org/?account=$fU", "$var(credit
Expand Down Expand Up @@ -402,7 +428,7 @@ $fU\n");
but in an asynchronous way. Script execution is suspended until
the entire content of the HTTP response is available.

Example 1.13. async rest_post usage
Example 1.14. async rest_post usage
route {
...
async(rest_post("http://myserver.org/register_user", "$fU", , "$
Expand Down Expand Up @@ -435,7 +461,7 @@ route [resume] {
but in an asynchronous way. Script execution is suspended until
the entire content of the HTTP response is available.

Example 1.14. async rest_put usage
Example 1.15. async rest_put usage
route {
...
async(rest_put("http://myserver.org/users/$fU", "$var(userinfo)"
Expand Down
53 changes: 46 additions & 7 deletions modules/rest_client/doc/rest_client_admin.xml
View file
Expand Up @@ -231,8 +231,7 @@ modparam("rest_client", "ssl_capath", "/home/opensips/ca_certificates")
</listitem>
</itemizedlist>
<para>
This function can be used from the <emphasis>startup, branch, failure,
request</emphasis> and <emphasis>timer</emphasis> routes.
This function can be used from any route.
</para>
<example>
<title><function moreinfo="none">rest_get</function> usage</title>
Expand Down Expand Up @@ -300,8 +299,7 @@ if ($var(rcode) >= 300) {
</listitem>
</itemizedlist>
<para>
This function can be used from the <emphasis>startup, branch, failure,
request</emphasis> and <emphasis>timer</emphasis> routes.
This function can be used from any route.
</para>
<example>
<title><function moreinfo="none">rest_post</function> usage</title>
Expand Down Expand Up @@ -370,8 +368,7 @@ if ($var(rcode) >= 300) {
</listitem>
</itemizedlist>
<para>
This function can be used from the <emphasis>startup, branch, failure,
request</emphasis> and <emphasis>timer</emphasis> routes.
This function can be used from any route.
</para>
<example>
<title><function moreinfo="none">rest_put</function> usage</title>
Expand Down Expand Up @@ -415,7 +412,7 @@ if ($var(rcode) >= 300) {
</listitem>
</itemizedlist>
<para>
This function can be used from the <emphasis>startup, branch, failure, request</emphasis> and <emphasis>timer</emphasis> routes.
This function can be used from any route.
</para>
<example>
<title><function moreinfo="none">rest_append_hf</function> usage</title>
Expand All @@ -425,6 +422,48 @@ if ($var(rcode) >= 300) {

rest_append_hf("Authorization: Bearer mF_9.B5f-4.1JqM");
$var(rc) = rest_get("http://getcredit.org/?account=$fU", "$var(credit)");
...
</programlisting>
</example>
</section>
<section id="rest_init_client_tls" xreflabel="rest_init_client_tls">
<title>
<function moreinfo="none">rest_init_client_tls(tls_client_domain)</function>
</title>
<para>
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.
</para>
<para>
If using this parameter, you must also ensure that tls_mgm is loaded
and properly configured.
</para>
<para>
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.
</para>
<para>Parameter types</para>
<itemizedlist>
<listitem>
<para><emphasis>tls_client_domain</emphasis> - string,
pseudo-variable, or a string which includes pseudo-variables.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from any route.
</para>
<example>
<title><function moreinfo="none">rest_init_client_tls</function> usage</title>
<programlisting format="linespecific">
...
rest_init_client_tls("1=10.11.12.13:3306");
if (!rest_get("https://example.com"))
xlog("query failed\n");
...
</programlisting>
</example>
Expand Down

0 comments on commit e004450

Please sign in to comment.