144 lines
8.5 KiB
HTML
144 lines
8.5 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta name="author" content="Basho Technologies" />
|
|
<meta name="description" content="Webmachine request/response data" />
|
|
<meta name="keywords" content="webmachine http rest web" />
|
|
<meta http-equiv="content-type" content="text/html;charset=utf-8" />
|
|
<link rel="stylesheet" href="css/style-1c.css" type="text/css" />
|
|
<title>Webmachine request/response data</title>
|
|
</head>
|
|
<body>
|
|
<div id="content">
|
|
<h1><span class="hr"></span><a href="/">webmachine</a></h1>
|
|
<ul id="top">
|
|
<li><a href="/">Home</a></li>
|
|
<li><a href="http://bitbucket.org/justin/webmachine/">Source Code</a></li>
|
|
<li><a href="contact.html">Contact</a></li>
|
|
</ul>
|
|
<div id="left">
|
|
<h3>Webmachine request/response data</h3>
|
|
|
|
<p>
|
|
|
|
This is documentation of the Webmachine Request Data API as embodied
|
|
by the <code>"wrq"</code> module. This module is the means by which
|
|
resources access and manipulate the state of the request they are
|
|
handling.
|
|
|
|
</p>
|
|
<p>
|
|
|
|
Given that all webmachine resource functions have this signature:
|
|
|
|
</p>
|
|
|
|
<span class="fwf">f(ReqData, Context) -> {Result, ReqData, Context}</span>
|
|
|
|
<p>
|
|
|
|
we should explain in detail the <code>ReqData</code> input and output
|
|
parameter. This is a data structure used to represent the request
|
|
sent by the client as well as the response being built by the
|
|
resource. The <code>wrq</code> module is used to access the values in
|
|
the input parameter. Most functions in most resources have no need to
|
|
modify the output <code>ReqData</code> and can simply pass along the
|
|
one received as input. However, in some cases a resource will need to
|
|
make some update to the response other than that implied by
|
|
<code>Result</code> and in those cases it should use the
|
|
<code>wrq</code> module to build a modified <code>ReqData</code> from
|
|
the original one for the return value.
|
|
|
|
</p>
|
|
<p>
|
|
|
|
A couple of nonstandard types are assumed here:
|
|
|
|
</p>
|
|
|
|
<table><tr><th>Type</th><th>Description</th></tr>
|
|
<tr><td>string()</td><td>a list() with all elements in the ASCII range</td></tr>
|
|
<tr><td>rd()</td><td>opaque record, used as the input/output <code>ReqData</code></td></tr>
|
|
<tr><td>streambody()</td><td>A webmachine <a href="streambody.html">streamed body format</a></td></tr>
|
|
<tr><td>mochiheaders()</td><td>a structure used in mochiweb for HTTP header storage</td></tr>
|
|
</table>
|
|
|
|
<p>The accessors are:</p>
|
|
|
|
<table><tr><th>Function</th><th>Description</th></tr>
|
|
<tr><td><code> method(rd()) -> 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'POST' | 'PUT' | 'TRACE' </code></td><td>The HTTP method used by the client. (note that it is an <code> atom() </code>)</td></tr>
|
|
|
|
<tr><td><code> version(rd()) -> {integer(),integer()} </code></td><td>The HTTP version used by the client. Most often <code> {1,1} </code>.</td></tr>
|
|
<tr><td><code> peer(rd()) -> string() </code></td><td>The IP address of the client.</td></tr>
|
|
<tr><td><code> disp_path(rd()) -> string() </code></td><td>The "local" path of the resource URI; the part after any prefix used in <a href="dispatcher.html">dispatch configuration</a>. Of the three path accessors, this is the one you usually want. This is also the one that will change after <code>create_path</code> is called in your <a href="resources.html">resource</a>.</td></tr>
|
|
|
|
<tr><td><code> path(rd()) -> string() </code></td><td>The path part of the URI -- after the host and port, but not including any query string.</td></tr>
|
|
<tr><td><code> raw_path(rd()) -> string() </code></td><td>The entire path part of the URI, including any query string present.</td></tr>
|
|
<tr><td><code> path_info(atom(),rd()) -> 'undefined' | string() </code></td><td>Looks up a binding as described in <a href="dispatcher.html">dispatch configuration</a>.</td></tr>
|
|
|
|
<tr><td><code> path_info(rd()) -> any() </code></td><td>The dictionary of bindings as described in <a href="dispatcher.html">dispatch configuration</a>.</td></tr>
|
|
<tr><td><code> path_tokens(rd()) -> list() </code></td><td>This is a list of <code> string() </code> terms, the disp_path components split by "/".</td></tr>
|
|
|
|
<tr><td><code> get_req_header(string(),rd()) -> 'undefined' | string() </code></td><td>Look up the value of an incoming request header.</td></tr>
|
|
<tr><td><code> req_headers(rd()) -> mochiheaders() </code></td><td>The incoming HTTP headers. Generally, get_req_header is more useful.</td></tr>
|
|
<tr><td><code> req_body(rd()) -> 'undefined' | binary() </code></td><td>The incoming request body, if any.</td></tr>
|
|
|
|
<tr><td><code> stream_req_body(rd(),integer()) -> streambody() </code></td><td>The incoming request body in <a href="streambody.html">streamed</a> form, with hunks no bigger than the integer argument.</td></tr>
|
|
<tr><td><code> get_cookie_value(string(),rd()) -> string() </code></td><td>Look up the named value in the incoming request cookie header.</td></tr>
|
|
<tr><td><code> req_cookie(rd()) -> string() </code></td><td>The raw value of the cookie header. Note that get_cookie_value is often more useful.</td></tr>
|
|
|
|
<tr><td><code> get_qs_value(string(),rd()) -> 'undefined' | string() </code></td><td>Given the name of a key, look up the corresponding value in the query string.</td></tr>
|
|
<tr><td><code> get_qs_value(string(),string(),rd()) -> string() </code></td><td>Given the name of a key and a default value if not present, look up the corresponding value in the query string.</td></tr>
|
|
<tr><td><code> req_qs(rd()) -> [{string(), string()}] </code></td><td>The parsed query string, if any. Note that get_qs_value is often more useful.</td></tr>
|
|
|
|
<tr><td><code> get_resp_header(string(),rd()) -> string() </code></td><td>Look up the current value of an outgoing request header.</td></tr>
|
|
<tr><td><code> resp_redirect(rd()) -> bool() </code></td><td>the last value passed to do_redirect, false otherwise -- if true, then some responses will be 303 instead of 2xx where applicable</td></tr>
|
|
<tr><td><code> resp_headers(rd()) -> mochiheaders() </code></td><td>The outgoing HTTP headers. Generally, get_resp_header is more useful.</td></tr>
|
|
|
|
<tr><td><code> resp_body(rd()) -> 'undefined' | binary() </code></td><td>The outgoing response body, if one has been set. Usually, append_to_response_body is the best way to set this.</td></tr>
|
|
<tr><td><code> app_root(rd()) -> string() </code></td><td>Indicates the "height" above the requested URI that this resource is dispatched from. Typical values are <code> "." </code>, <code> ".." </code>, <code> "../.." </code> and so on.</td></tr>
|
|
|
|
</table>
|
|
|
|
|
|
<p
|
|
>The functions for (nondestructive) modification of <code> rd() </code> terms are:
|
|
</p>
|
|
|
|
|
|
<table><tr><th>Function</th><th>Description</th></tr>
|
|
<tr><td><code> set_resp_header(string(),string(),rd()) -> rd() </code></td><td>Given a header name and value, set an outgoing request header to that value.</td></tr>
|
|
<tr><td><code> append_to_response_body(binary(),rd()) -> rd() </code></td><td>Append the given value to the body of the outgoing response.</td></tr>
|
|
|
|
<tr><td><code> do_redirect(bool(),rd()) -> rd() </code></td><td>see resp_redirect; this sets that value.</td></tr>
|
|
<tr><td><code> set_disp_path(string(),rd()) -> rd() </code></td><td>The disp_path is the only path that can be changed during a request. This function will do so.</td></tr>
|
|
<tr><td><code> set_req_body(binary(),rd()) -> rd() </code></td><td>Replace the incoming request body with this for the rest of the processing.</td></tr>
|
|
|
|
<tr><td><code> set_resp_body(binary(),rd()) -> rd() </code></td><td>Set the outgoing response body to this value.</td></tr>
|
|
<tr><td><code> set_resp_body(streambody(),rd()) -> rd() </code></td><td>Use this <a href="streambody.html">streamed body</a> to produce the outgoing response body on demand.</td></tr>
|
|
<tr><td><code> set_resp_headers([{string(),string()}],rd()) -> rd() </code></td><td>Given a list of two-tuples of {headername,value}, set those outgoing response headers.</td></tr>
|
|
|
|
<tr><td><code> remove_resp_header(string(),rd()) -> rd() </code></td><td>Remove the named outgoing response header.</td></tr>
|
|
</table>
|
|
|
|
|
|
</div>
|
|
<div id="footer">
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<script type="text/javascript">
|
|
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
|
|
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
|
|
</script>
|
|
<script type="text/javascript">
|
|
try {
|
|
var pageTracker = _gat._getTracker("UA-4979965-5");
|
|
pageTracker._trackPageview();
|
|
} catch(err) {}</script>
|
|
|
|
</body>
|
|
</html>
|
|
|