122 lines
4.8 KiB
HTML
122 lines
4.8 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 dispatching" />
|
||
|
|
<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 dispatching</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 dispatching</h3>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
This page describes the configuration of URI dispatch to resources
|
||
|
|
in a webmachine application. The dispatch map data structure is a list
|
||
|
|
of 3-tuples, where each entry is of the form {pathspec, resource,
|
||
|
|
args}. The first pathspec in the list that matches the URI for a
|
||
|
|
request will cause the corresponding resource to be used in handling
|
||
|
|
that request.
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
|
||
|
|
A <code>pathspec</code> is a list of pathterms. A pathterm is any of
|
||
|
|
[string,atom,star] where star is just the atom of "*". The
|
||
|
|
pathspec-matching is done by breaking up the request URI into tokens
|
||
|
|
via the "/" separator and matching those tokens against the
|
||
|
|
pathterms. A string pathterm will match a token if the token is equal
|
||
|
|
to that string. A non-star atom will match any single token. The star
|
||
|
|
atom (* in single quotes) will match any number of tokens, but may
|
||
|
|
only be present as the last pathterm in a pathspec. If all tokens are
|
||
|
|
matched and all pathterms are used, then the pathspec matches. The
|
||
|
|
tokens used are available in <code>wrq:path_tokens(ReqData)</code>
|
||
|
|
in the resource functions.
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
|
||
|
|
Any atom pathterms that were used in a match will cause a binding in
|
||
|
|
the path_info element of the request's
|
||
|
|
<a href="reqdata.html">ReqData</a>. If
|
||
|
|
there was a <code>foo</code> atom that matched the token
|
||
|
|
<code>"bar"</code>, then <code>wrq:path_info(foo, ReqData)</code> will
|
||
|
|
return <code>"bar"</code> inside the resource calls, and in any case
|
||
|
|
<code>wrq:path_info(ReqData)</code> will return a Dict term with all
|
||
|
|
the bindings, accessible via the <code>dict</code> standard library
|
||
|
|
module. If there was a star pathterm in the pathspec, then
|
||
|
|
<code>wrq:disp_path(ReqData)</code> in a resource function will return
|
||
|
|
the URI portion that was matched by the star.
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
|
||
|
|
The <code> resource </code> is an atom identifying a
|
||
|
|
<a href="resources.html">resource</a> that
|
||
|
|
should handle a matching request. It will have the <code>args</code>
|
||
|
|
(which must be a list) passed to its init function before request
|
||
|
|
handling begins.
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
|
||
|
|
In the default directory structure for a new webmachine application,
|
||
|
|
the dispatch terms will be in file:consult form in
|
||
|
|
"priv/dispatch.conf" under the application root.
|
||
|
|
|
||
|
|
</p>
|
||
|
|
<h3 id="examples">Examples</h3>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
|
||
|
|
The examples below are taken from
|
||
|
|
<a href="http://www.erlang-factory.com/conference/SFBayAreaErlangFactory2009/speakers/justinsheehy">Justin Sheehy's slide at Erlang Factory 2009</a>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<table><tr><th>Dispatch Rule</th><th>URL</th><th>wrq:disp_path</th><th>wrq:path</th><th>wrq:path_info</th><th>wrq:path_tokens</th></tr>
|
||
|
|
<tr><td>{["a"], some_resource, []}</td><td>/a</td><td>""</td><td>"/a"</td><td>[]</td><td>[]</td></tr>
|
||
|
|
|
||
|
|
<tr><td>{["a", '*'], some_resource, []}</td><td>/a</td><td>""</td><td>"/a"</td><td>[]</td><td>[]</td></tr>
|
||
|
|
<tr><td>{["a", '*'], some_resource, []}</td><td>/a/b/c</td><td>"b/c"</td><td>"/a/b/c"</td><td>[]</td><td>["b", "c"]</td></tr>
|
||
|
|
<tr><td>{["a", foo], some_resource, []}</td><td>/a/b</td><td>""</td><td>"/a/b"</td><td>[{foo, "b"}]</td><td>[]</td></tr>
|
||
|
|
|
||
|
|
<tr><td>{["a", foo, '*'], some_resource, []}</td><td>/a/b</td><td>""</td><td>"/a/b"</td><td>[{foo, "b"}]</td><td>[]</td></tr>
|
||
|
|
<tr><td>{["a", foo, '*'], some_resource, []}</td><td>/a/b/c/d</td><td>"c/d"</td><td>"/a/b/c/d"</td><td>[{foo, "b"}]</td><td>["c", "d"]</td></tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>Query strings are easy too:</p>
|
||
|
|
|
||
|
|
<ul><li>Given rule: {["a", foo, '*'], some_resource, []}
|
||
|
|
</li><li>And URL: /a/b/c/d?fee=ah&fie=ha
|
||
|
|
</li><li>Then wrq:get_qs_value("fie",ReqData) -> "ha"
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
</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>
|
||
|
|
|