processmaker-builder
Version:
The gulp task runner for ProcessMaker building
492 lines (367 loc) • 26.5 kB
HTML
<html>
<head>
<title>Luracast Restler 3 Live Examples:- Routing</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="../resources/bootstrap.min.css" />
<link rel="stylesheet" type="text/css" href="../resources/highlight.css" />
<link rel="stylesheet" type="text/css" href="../resources/style.css" />
<link rel="stylesheet" type="text/css" href="../resources/facebox.css" />
<link rel="stylesheet" type="text/css" href="../resources/hacks.css" />
<script type="text/javascript" src="../resources/jquery-1.7.2.min.js"></script>
<script type="text/javascript" src="../resources/facebox.js"></script>
<script type="text/javascript" src="../resources/bootstrap.min.js"></script>
<script type="text/javascript" src="../resources/highlight.pack.js"></script>
<script type="text/javascript">
$(document).ready(
function() {
$('dd pre code').each(function(i, e) {
text = $(e).text();
$(e).addClass(text.charAt(0) == '<' ? 'xml' : 'json')
//hljs.highlightBlock(e);
});
$('pre code').each(function(i, e) {
if($(e).attr('class'))
hljs.highlightBlock(e);
});
$('abbr').parents().not('a').children('abbr').click(
function() {
$('#codeviewer').load(
'../resources/getsource.php?file='
+ $(this).attr("title"),
function() {
/*
$("pre#php").snippet("php", {
style : "acid",
showNum : false
});
*/
jQuery.facebox({
div : '#codeviewer'
});
hljs.highlightBlock($("pre#php")[1]);
});
});
var curURL = window.location.pathname.split('/examples/')[1];
if (curURL == '')
curURL = 'index.html';
$("a").each(function() {
if ($(this).attr("href") && $(this).attr("href").indexOf(curURL) > -1) {
$(this).addClass("active");
}
});
$('#right tag').popover({
html : true,
placement : 'left',
trigger : 'manual',
title : 'Tagged Examples',
content : '...'
}).click(function(e) {
$('#right tag').popover('hide');
$(this).popover('show');
e.preventDefault();
e.stopPropagation ? e.stopPropagation() : e.cancelBubble = true;
});
$(document).click(function(e) {
$('#right tag').popover('hide');
});
})
</script>
<!--[if lte IE 8]>
<script type="text/javascript">
(function(){if(!/*@cc_on!@*/0)return;var e = "abbr,article,aside,audio,bb,canvas,datagrid,datalist,details,dialog,eventsource,figure,footer,header,hgroup,mark,menu,meter,nav,output,progress,section,time,video,tag".split(',');for(var i=0;i<e.length;i++){document.createElement(e[i])}})()
</script>
<![endif]-->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-23777019-2']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<nav class="floating-menu">
<ul>
<li><a title="Restler Home" target="_blank" href="http://luracast.com/products/restler/"><img src="../resources/home.png" width="16" height="16"/> Home</a></li>
<li><a title="Getting Started with Restler" href="../.."><img src="../resources/quickstart.png" width="16" height="16"/> Start</a></li>
<!--<li><a title="Using Restler" href="#">Guide</a></li><li><a title="Restler API Reference" href="#">API</a></li>-->
<li><a class="active" href="../index.html"><img src="../resources/examples.png" width="16" height="16"/> Examples</a></li>
<li><a title="Share your knowledge by answering user questions in Stack Overflow." target="_blank" href="http://bit.ly/Restler-QA"><img src="../resources/stackoverflow.png" width="16" height="16"/> Support</a></li>
<li><a title="Contribute and Fork Restler on GitHub" target="_blank" href="http://bit.ly/LuracastRestler"><img src="../resources/github.png" width="16" height="16"/> Source</a></li>
<li><a title="Get updated on Twitter" target="_blank" href="http://twitter.com/Luracast"><img src="../resources/twitter.png" width="16" height="16"/> Update</a></li>
<li><a title="Keep in touch on Facebook" target="_blank" href="https://www.facebook.com/Luracast"><img src="../resources/facebook.png" width="16" height="16"/> Connect</a></li>
</ul>
</nav>
<div id="codeviewer" style="display: none;"></div>
<nav id="left">
<img src="../resources/Restler3.gif" width="126"
height="126" title="Luracast Restler 3" />
<h3>
<a href="../index.html">Examples</a>
</h3>
<ul>
<li><a href="../_001_helloworld/readme.html" title="Let's say hello!">Hello World</a></li>
<li><a href="../_002_minimal/readme.html" title="Less is more">Minimal</a></li>
<li><a href="../_003_multiformat/readme.html" title="Serving what the client wants">Multi-format</a></li>
<li><a href="../_004_error_response/readme.html" title="Making use of HTTP status codes">Error Response</a></li>
<li><a href="../_005_protected_api/readme.html" title="Creating restricted zone">Protected API</a></li>
<li><a href="../_006_routing/readme.html" title="Ways to map api methods to url">Routing</a></li>
<li><a href="../_007_crud/readme.html" title="using POST, GET, PUT and DELETE">CRUD</a></li>
<li><a href="../_008_documentation/readme.html" title="Commenting can be more rewarding">Documentation</a></li>
<li><a href="../_009_rate_limiting/readme.html" title="Abuse no more">Rate Limiting</a></li>
<li><a href="../_010_access_control/readme.html" title="Who can do what">Access Control</a></li>
<li><a href="../_011_versioning/readme.html" title="using the URL">Versioning</a></li>
<li><a href="../_012_vendor_mime/readme.html" title="custom media type for versioning">Vendor MIME</a></li>
<li><a href="../_013_html/readme.html" title="rendering custom views">Html Format</a></li>
<li><a href="../_014_oauth2_client/readme.html" title="to consume protected API">OAuth2 Client</a></li>
<li><a href="../_015_oauth2_server/readme.html" title="offering protected API">OAuth2 Server</a></li>
<li><a href="../_016_forms/readme.html" title="to capture user input">Forms</a></li>
</ul>
</nav>
<nav id="right">
<h3><a href="../index.html">Examples by Tag</a></h3>
<ul class="tags">
<li><tag title="Access-control Example(s)" data-content="<a href="../_010_access_control/readme.html">Access Control</a> <a href="../_014_oauth2_client/readme.html">OAuth2 Client</a> <a href="../_015_oauth2_server/readme.html">OAuth2 Server</a>">access-control</tag><badge>3</badge></li>
<li><tag title="Acl Example(s)" data-content="<a href="../_010_access_control/readme.html">Access Control</a> <a href="../_014_oauth2_client/readme.html">OAuth2 Client</a> <a href="../_015_oauth2_server/readme.html">OAuth2 Server</a>">acl</tag><badge>3</badge></li>
<li><tag title="Authentication Example(s)" data-content="<a href="../_005_protected_api/readme.html">Protected API</a> <a href="../_010_access_control/readme.html">Access Control</a> <a href="../_014_oauth2_client/readme.html">OAuth2 Client</a> <a href="../_015_oauth2_server/readme.html">OAuth2 Server</a>">authentication</tag><badge>4</badge></li>
<li><tag title="Authorization Example(s)" data-content="<a href="../_005_protected_api/readme.html">Protected API</a> <a href="../_010_access_control/readme.html">Access Control</a> <a href="../_014_oauth2_client/readme.html">OAuth2 Client</a> <a href="../_015_oauth2_server/readme.html">OAuth2 Server</a>">authorization</tag><badge>4</badge></li>
<li><tag title="Basic Example(s)" data-content="<a href="../_001_helloworld/readme.html">Hello World Example</a> <a href="../_002_minimal/readme.html">Minimal Example</a>">basic</tag><badge>2</badge></li>
<li><tag title="Blade Example(s)" data-content="<a href="../_016_forms/readme.html">Forms Example</a>">blade</tag></li>
<li><tag title="Bootstrap Example(s)" data-content="<a href="../_016_forms/readme.html">Forms Example</a>">bootstrap</tag></li>
<li><tag title="Create Example(s)" data-content="<a href="../_007_crud/readme.html">CRUD</a> <a href="../_008_documentation/readme.html">Documentation</a> <a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">create</tag><badge>3</badge></li>
<li><tag title="Custom Example(s)" data-content="<a href="../_012_vendor_mime/readme.html">Vendor MIME</a>">custom</tag></li>
<li><tag title="Debug Example(s)" data-content="<a href="../_008_documentation/readme.html">Documentation</a>">debug</tag></li>
<li><tag title="Delete Example(s)" data-content="<a href="../_006_routing/readme.html">Routing</a> <a href="../_007_crud/readme.html">CRUD</a> <a href="../_008_documentation/readme.html">Documentation</a> <a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">delete</tag><badge>4</badge></li>
<li><tag title="Doc Example(s)" data-content="<a href="../_008_documentation/readme.html">Documentation</a>">doc</tag></li>
<li><tag title="Emmet Example(s)" data-content="<a href="../_016_forms/readme.html">Forms Example</a>">emmet</tag></li>
<li><tag title="Exception Example(s)" data-content="<a href="../_004_error_response/readme.html">Error Response</a>">exception</tag></li>
<li><tag title="Filter Example(s)" data-content="<a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">filter</tag></li>
<li><tag title="Form Example(s)" data-content="<a href="../_016_forms/readme.html">Forms Example</a>">form</tag></li>
<li><tag title="Foundation Example(s)" data-content="<a href="../_016_forms/readme.html">Forms Example</a>">foundation</tag></li>
<li><tag title="Get Example(s)" data-content="<a href="../_006_routing/readme.html">Routing</a> <a href="../_007_crud/readme.html">CRUD</a> <a href="../_008_documentation/readme.html">Documentation</a> <a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">get</tag><badge>4</badge></li>
<li><tag title="Handlebar Example(s)" data-content="<a href="../_013_html/readme.html">Html Format</a>">handlebar</tag></li>
<li><tag title="Html Example(s)" data-content="<a href="../_013_html/readme.html">Html Format</a> <a href="../_016_forms/readme.html">Forms Example</a>">html</tag><badge>2</badge></li>
<li><tag title="Http Status Example(s)" data-content="<a href="../_002_minimal/readme.html">Minimal Example</a> <a href="../_004_error_response/readme.html">Error Response</a>">http status</tag><badge>2</badge></li>
<li><tag title="Json Example(s)" data-content="<a href="../_003_multiformat/readme.html">Multi-format</a>">json</tag></li>
<li><tag title="Mediatype Example(s)" data-content="<a href="../_012_vendor_mime/readme.html">Vendor MIME</a>">mediatype</tag></li>
<li><tag title="Mime Example(s)" data-content="<a href="../_012_vendor_mime/readme.html">Vendor MIME</a>">mime</tag></li>
<li><tag title="Mustache Example(s)" data-content="<a href="../_013_html/readme.html">Html Format</a>">mustache</tag></li>
<li><tag title="Patch Example(s)" data-content="<a href="../_006_routing/readme.html">Routing</a>">patch</tag></li>
<li><tag title="Php Example(s)" data-content="<a href="../_013_html/readme.html">Html Format</a>">php</tag></li>
<li><tag title="Post Example(s)" data-content="<a href="../_006_routing/readme.html">Routing</a> <a href="../_007_crud/readme.html">CRUD</a> <a href="../_008_documentation/readme.html">Documentation</a> <a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">post</tag><badge>4</badge></li>
<li><tag title="Production Example(s)" data-content="<a href="../_008_documentation/readme.html">Documentation</a>">production</tag></li>
<li><tag title="Put Example(s)" data-content="<a href="../_006_routing/readme.html">Routing</a> <a href="../_007_crud/readme.html">CRUD</a> <a href="../_008_documentation/readme.html">Documentation</a> <a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">put</tag><badge>4</badge></li>
<li><tag title="Rate-limiting Example(s)" data-content="<a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">rate-limiting</tag></li>
<li><tag title="Read Example(s)" data-content="<a href="../_007_crud/readme.html">CRUD</a> <a href="../_008_documentation/readme.html">Documentation</a> <a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">read</tag><badge>3</badge></li>
<li><tag title="Retrieve Example(s)" data-content="<a href="../_007_crud/readme.html">CRUD</a> <a href="../_008_documentation/readme.html">Documentation</a> <a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">retrieve</tag><badge>3</badge></li>
<li><tag title="Routing Example(s)" data-content="<a href="../_006_routing/readme.html">Routing</a> <a href="../_007_crud/readme.html">CRUD</a> <a href="../_008_documentation/readme.html">Documentation</a>">routing</tag><badge>3</badge></li>
<li><tag title="Secure Example(s)" data-content="<a href="../_010_access_control/readme.html">Access Control</a> <a href="../_014_oauth2_client/readme.html">OAuth2 Client</a> <a href="../_015_oauth2_server/readme.html">OAuth2 Server</a>">secure</tag><badge>3</badge></li>
<li><tag title="Template Example(s)" data-content="<a href="../_013_html/readme.html">Html Format</a>">template</tag></li>
<li><tag title="Throttle Example(s)" data-content="<a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">throttle</tag></li>
<li><tag title="Twig Example(s)" data-content="<a href="../_013_html/readme.html">Html Format</a>">twig</tag></li>
<li><tag title="Update Example(s)" data-content="<a href="../_007_crud/readme.html">CRUD</a> <a href="../_008_documentation/readme.html">Documentation</a> <a href="../_009_rate_limiting/readme.html">Rate Limiting</a>">update</tag><badge>3</badge></li>
<li><tag title="Validation Example(s)" data-content="<a href="../_002_minimal/readme.html">Minimal Example</a> <a href="../_004_error_response/readme.html">Error Response</a> <a href="../_016_forms/readme.html">Forms Example</a>">validation</tag><badge>3</badge></li>
<li><tag title="Vendor Example(s)" data-content="<a href="../_012_vendor_mime/readme.html">Vendor MIME</a>">vendor</tag></li>
<li><tag title="Versioning Example(s)" data-content="<a href="../_011_versioning/readme.html">Versioning</a> <a href="../_012_vendor_mime/readme.html">Vendor MIME</a>">versioning</tag><badge>2</badge></li>
<li><tag title="View Example(s)" data-content="<a href="../_013_html/readme.html">Html Format</a>">view</tag></li>
<li><tag title="Xml Example(s)" data-content="<a href="../_003_multiformat/readme.html">Multi-format</a>">xml</tag></li>
</ul>
</nav>
<article id="page">
<div class="right"><small>6</small></div>
<p><a id="routing" class="anchor"></a><h2>Routing <requires>PHP >= 5.3</requires></h2></p>
<p><tag>routing</tag>
<tag>get</tag>
<tag>post</tag>
<tag>put</tag>
<tag>delete</tag>
<tag>patch</tag></p>
<p><a id="two-ways-of-routing" class="anchor"></a><h3>Two ways of Routing</h3></p>
<p>API Methods can be mapped to URI in two ways</p>
<ol>
<li>Automatic Routing</li>
<li>Manual Routing</li>
</ol>
<p><a id="how-automatic-routing-is-done" class="anchor"></a><h3>How automatic routing is done?</h3></p>
<p><strong>Role of Class Name</strong></p>
<p>When the api class is added without specifying the path prefix, name of the
class will be used as path prefix</p>
<p><strong>Mapping to HTTP Verbs (GET, POST, PUT, DELETE, PATCH)</strong></p>
<p>Restler uses <em>get, put, post, delete, and patch</em> as prefix to map PHP methods to
respective HTTP methods. When they are used method names with out any suffix
they map at the class level similar to <em>index</em></p>
<pre><code>{HTTP_METHOD} class_name
</code></pre>
<p>GET is the default HTTP method so all public functions without any of
these prefixes will be mapped to GET request. This means functions
<em>getResult</em> and <em>result</em> will both be mapped to</p>
<pre><code>GET class_name/result
</code></pre>
<p>Similarly method <em>postSomething</em> will be mapped to</p>
<pre><code>POST class_name/something
</code></pre>
<p><strong>Smart Parameter Routing</strong></p>
<p>Starting from Restler 3, smart auto routes are created where optional
parameters will be mapped to query string, required primitive types,
objects and arrays will be mapped to request body.</p>
<blockquote>
<p><strong>Note:-</strong> Required primitive types used to be mapped to url path. This behavior
has changed in favour of better and readable urls.</p>
</blockquote>
<p>This helps build as few URIs as possible for the given API method,
reducing the ambiguity.</p>
<p>If the restler 2 ways of routing is preferred, where all parameters can be sent
using url path or query string or body, you can use the following code in the
<abbr title="_006_routing/index.php">index.php</abbr> (gateway)</p>
<pre><code>Defaults::$smartAutoRouting = false;
</code></pre>
<p>It can also be set at the class level or method level with the following php doc
comment.</p>
<pre><code>@smart-auto-routing false
</code></pre>
<p><a id="manual-routing" class="anchor"></a><h3>Manual Routing</h3></p>
<p><strong>Role of Class Name</strong></p>
<p>When you add the api class, use the second, optional parameter to specify the
url segment to map it to, you may choose to keep it blank to map it to the root</p>
<pre><code>$r->addAPIClass('MyClass','');
</code></pre>
<p><a id="rest-of-the-uri" class="anchor"></a><h3>Rest of the URI</h3></p>
<p>rest of the uri can be created manually using php doc comment as shown below or
else automatically routed for public and protected methods unless they are
marked with <code>@access private</code>. We can specify as many routes as we want for a
single method. Comment structure is as shown below</p>
<pre><code>@url {HTTP_METHOD} path_segment_including_url_parameters
</code></pre>
<p>For example</p>
<pre><code>@url POST custom/path/{var1}/{var2}
</code></pre>
<p><a id="wildcard-routes" class="anchor"></a><h3>Wildcard Routes</h3></p>
<p>Wildcard routes allows our api methods to receive variable number of parameters
they are manual routes that end with a star as the last path segment</p>
<p>For example</p>
<pre><code>@url GET custom/path/*
</code></pre>
<p>Take a look at the api class used here and compare it with the routes below to
understand.</p>
<blockquote>
<p>This API Server is made using the following php files/folders</p>
<ul>
<li><abbr title="_006_routing/index.php">index.php</abbr> (gateway)</li>
<li><abbr title="_006_routing/Api.php">Api.php</abbr> (api)</li>
<li><abbr title="../../vendor/restler.php">restler.php</abbr> (framework)</li>
<li><abbr title="../../vendor/Luracast/Restler/Format/JsonFormat.php">JsonFormat.php</abbr> (format)</li>
</ul>
</blockquote>
<p>This API Server exposes the following URIs</p>
<pre><code>GET api/all/* ⇠ Api::allIsMine()
POST api/method ⇠ Api::postMethod()
POST api/method2 ⇠ Api::whatEver()
POST api/method2/{anything} ⇠ Api::whatEver()
GET api/somanyways ⇠ Api::soManyWays()
GET api/somanyways/{p1} ⇠ Api::soManyWays()
GET api/somanyways/{p1}/{p2} ⇠ Api::soManyWays()
GET api/somanyways/{p1}/{p2}/{p3} ⇠ Api::soManyWays()
GET api/what/ever/you/want ⇠ Api::whatEver()
</code></pre>
<p>Try the following links in your browser</p>
<dl>
<dt>GET <a href="index.php/api/somanyways/1?p2=something" target="_blank">api/somanyways/1?p2=something</a></dt>
<dd>
<p></p>
<pre><code>"you have called Api::soManyWays()"
</code></pre>
</dd>
<dt>GET <a href="index.php/api/somanyways/1/2" target="_blank">api/somanyways/1/2</a></dt>
<dd><pre><code>"you have called Api::soManyWays()"
</code></pre></dd>
<dl>
<dt>GET <a href="index.php/api/somanyways/1/2/3" target="_blank">api/somanyways/1/2/3</a></dt>
<dd>
<p></p>
<pre><code>"you have called Api::soManyWays()"
</code></pre>
</dd>
<dt>GET <a href="index.php/api/what/ever/you/want" target="_blank">api/what/ever/you/want</a></dt>
<dd><pre><code>{
"error": {
"code": 400,
"message": "Bad Request: anything is missing."
}
}
</code></pre></dd>
<dl>
<dt>GET <a href="index.php/api/what/ever/you/want?anything=something" target="_blank">api/what/ever/you/want?anything=something</a></dt>
<dd>
<p></p>
<pre><code>"you have called Api::whatEver()"
</code></pre>
</dd>
<dt>GET <a href="index.php/api/all/1/2/3/4/5/6/7" target="_blank">api/all/1/2/3/4/5/6/7</a></dt>
<dd><pre><code>"you have called Api::allIsMine(1, 2, 3, 4, 5, 6, 7)"
</code></pre></dd>
<dl>
<dt>GET <a href="index.php/api/all" target="_blank">api/all</a></dt>
<dd>
<p></p>
<pre><code>"you have called Api::allIsMine()"
</code></pre>
</dd>
</dl>
<p>We expect the following behaviour from this example.</p>
<pre><code class="gherkin"><br />@example6 @routing
Feature: Testing Routing Example
Scenario: Testing So Many Ways
Given that "p2" is set to 2
When I request "/examples/_006_routing/api/somanyways/1{?p2}"
Then the response status code should be 200
And the response is JSON
And the type is "string"
And the value equals "you have called Api::soManyWays()"
Scenario: Testing So Many Ways with two params
When I request "/examples/_006_routing/api/somanyways/1/2"
Then the response status code should be 200
And the response is JSON
And the type is "string"
And the value equals "you have called Api::soManyWays()"
Scenario: Testing So Many Ways with three params
When I request "/examples/_006_routing/api/somanyways/1/2/3"
Then the response status code should be 200
And the response is JSON
And the type is "string"
And the value equals "you have called Api::soManyWays()"
Scenario: Testing So Many Ways with more params
When I request "/examples/_006_routing/api/somanyways/1/2/3/4"
Then the response status code should be 404
And the response is JSON
Scenario: Ignoring required parameter should throw 400
When I request "/examples/_006_routing/api/what/ever/you/want"
Then the response status code should be 400
And the response is JSON
Scenario: Testing Wildcard route with 7 parameters
When I request "/examples/_006_routing/api/all/1/2/3/4/5/6/7"
Then the response status code should be 200
And the response is JSON
And the type is "string"
And the value equals "you have called Api::allIsMine(1, 2, 3, 4, 5, 6, 7)"
Scenario: Testing Wildcard route with 0 parameters
When I request "/examples/_006_routing/api/all"
Then the response status code should be 200
And the response is JSON
And the type is "string"
And the value equals "you have called Api::allIsMine()"
</code></pre>
<p>It can be tested by running the following command on terminal/command line
from the project root (where the vendor folder resides). Make sure <code>base_url</code>
in <code>behat.yml</code> is updated according to your web server.</p>
<pre><code class="bash">bin/behat features/examples/_006_routing.feature
</code></pre>
</article>
<footer>
© 2010 <a title="Luracast.com" href="http://luracast.com"><img src="../resources/Luracast_dark.png" width="180" height="32" title="Helping Developers with Tools, Utilities, Frameworks and Services"/></a>
</footer>
</body>
</html>