Skip to content

Commit

Permalink
Merge pull request #970 from AgalyaR/master
Browse files Browse the repository at this point in the history 
Documentation updated for REST_PUT
  • Loading branch information
@liviuchircu
liviuchircu committed Oct 20, 2016
2 parents 7de2933 + d0e0a30 commit d67a009
Show file tree
Hide file tree
Showing 2 changed files with 179 additions and 10 deletions.
94 changes: 85 additions & 9 deletions modules/rest_client/README
View file
Expand Up @@ -42,7 +42,11 @@ Liviu Chircu
recv_body_pv[, [recv_ctype_pv][,
[retcode_pv]]])

1.4.3. rest_append_hf(txt)
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.5. Exported Asynchronous Functions

Expand All @@ -53,6 +57,10 @@ Liviu Chircu
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]]])

List of Examples

1.1. Setting the connection_timeout parameter
Expand All @@ -63,16 +71,18 @@ Liviu Chircu
1.6. Setting the ssl_capath parameter
1.7. rest_get usage
1.8. rest_post usage
1.9. rest_append_hf usage
1.10. async rest_get usage
1.11. async rest_post usage
1.9. rest_put usage
1.10. rest_append_hf usage
1.11. async rest_get usage
1.12. async rest_post usage
1.13. 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 and POST.
HTTP server by doing RESTful queries, such as GET,PUT and POST.

1.2. Dependencies

Expand Down Expand Up @@ -237,7 +247,47 @@ if (!rest_post("http://myserver.org/register_user", "$fU", , "$var(body)
}
...

1.4.3. rest_append_hf(txt)

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

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.

Example 1.9. rest_put usage
...
# Storing data using a RESTful service with an HTTP PUT request

if (!rest_put("http://myserver.org/register_user", "$fU", , "$var(body)"
, "$var(ct)", "$var(rcode)")) {
xlog("Error code $var(rcode) in HTTP PUT!\n");
send_reply("403", "PUT Forbidden");
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
Expand All @@ -254,7 +304,7 @@ if (!rest_post("http://myserver.org/register_user", "$fU", , "$var(body)
This function can be used from the startup, branch, failure,
request and timer routes.

Example 1.9. rest_append_hf usage
Example 1.10. rest_append_hf usage
...
# Example of querying a REST service requiring additional headers

Expand All @@ -273,7 +323,7 @@ if (!rest_get("http://getcredit.org/?ruri=$fU", "$var(credit)")) {
but in an asynchronous way. Script execution is suspended until
the entire content of the HTTP response if available.

Example 1.10. async rest_get usage
Example 1.11. async rest_get usage
route {
...
async(rest_get("http://getcredit.org/?ruri=$fU", "$var(credit)",
Expand All @@ -298,7 +348,7 @@ route [resume]
but in an asynchronous way. Script execution is suspended until
the entire content of the HTTP response if available.

Example 1.11. async rest_post usage
Example 1.12. async rest_post usage
route {
...
async(rest_post("http://myserver.org/register_user", "$fU", , "$
Expand All @@ -314,3 +364,29 @@ route [resume]
}
......
}


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 if available.

Example 1.13. async rest_put usage
route {
...
async(rest_put("http://myserver.org/register_user", "$fU", , "$v
ar(body)", "$var(ct)", "$var(rcode)"), resume);
}

route [resume]
{
if ($rc < 0) {
xlog("Error code $var(rcode) in HTTP PUT!\n");
send_reply("403", "PUT Forbidden");
exit;
}
......
}
95 changes: 94 additions & 1 deletion modules/rest_client/doc/rest_client_admin.xml
View file
Expand Up @@ -8,7 +8,7 @@
<title>Overview</title>
<para>
The <emphasis>rest_client</emphasis> module provides a means of interacting
with an HTTP server by doing RESTful queries, such as GET and POST.
with an HTTP server by doing RESTful queries, such as GET,PUT and POST.
</para>
</section>

Expand Down Expand Up @@ -281,6 +281,65 @@ if (!rest_post("http://myserver.org/register_user", "$fU", , "$var(body)", "$var
exit;
}
...

</programlisting>
</example>
</section>
<section id="rest_put"
xreflabel="rest_put">
<title>
<function moreinfo="none">rest_put(url, send_body_pv, [send_ctype_pv],
recv_body_pv[, [recv_ctype_pv][, [retcode_pv]]])
</function>
</title>
<para>
Issues an HTTP PUT request to the specified <emphasis>url</emphasis>. The request body will
be copied from the <emphasis>send_body_pv</emphasis> pseudo-variable. The MIME Content-Type
header for the request will be taken from <emphasis>send_ctype_pv</emphasis> (default is
<emphasis>"application/x-www-form-urlencoded"</emphasis>)
</para>
<para>
The mandatory <emphasis>recv_body_pv</emphasis> pseudo-var will hold the body of the HTTP
response.
</para>
<para>
The optional <emphasis>recv_ctype_pv</emphasis> parameter will contain
the value of the "Content-Type" header of the response message.
</para>
<para>
The optional <emphasis>retcode_pv</emphasis> 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 <emphasis role='bold'>0</emphasis> value
means no HTTP reply arrived at all.
</para>
<para>Possible parameter types</para>
<itemizedlist>
<listitem>
<para><emphasis>url, send_body_pv, send_type_pv</emphasis> -
String, pseudo-variable, or a String which includes pseudo-variables.
</para>
</listitem>
<listitem>
<para><emphasis>recv_body_pv, recv_ctype_pv, retcode_pv</emphasis> -
pseudo-variables</para>
</listitem>
</itemizedlist>
<para>
This function can be used from the <emphasis>startup, branch, failure,
request</emphasis> and <emphasis>timer</emphasis> routes.
</para>
<example>
<title><function moreinfo="none">rest_put</function> usage</title>
<programlisting format="linespecific">
...
# Storing data using a RESTful service with an HTTP PUT request

if (!rest_put("http://myserver.org/register_user", "$fU", , "$var(body)", "$var(ct)", "$var(rcode)")) {
xlog("Error code $var(rcode) in HTTP PUT!\n");
send_reply("403", "PUT Forbidden");
exit;
}
...
</programlisting>
</example>
</section>
Expand Down Expand Up @@ -387,6 +446,40 @@ route [resume]
}
......
}

</programlisting>
</example>
</section>

<section>
<title>
<function moreinfo="none">rest_put(url, send_body_pv, [send_ctype_pv],
recv_body_pv[, [recv_ctype_pv][, [retcode_pv]]])
</function>
</title>
<para>
Sends a PUT HTTP request. This function behaves exactly the same as
<emphasis role='bold'><xref linkend="rest_put"/></emphasis> (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.
</para>
<example>
<title><function moreinfo="none">async rest_put</function> usage</title>
<programlisting format="linespecific">
route {
...
async(rest_put("http://myserver.org/register_user", "$fU", , "$var(body)", "$var(ct)", "$var(rcode)"), resume);
}

route [resume]
{
if ($rc &lt; 0) {
xlog("Error code $var(rcode) in HTTP PUT!\n");
send_reply("403", "PUT Forbidden");
exit;
}
......
}
</programlisting>
</example>
</section>
Expand Down

0 comments on commit d67a009

Please sign in to comment.