Author: keith Date: Sun Jan 27 02:07:13 2008 New Revision: 12992 Log:
adding a page for resty services Added: trunk/mashup/java/xdocs/restyservices.html Added: trunk/mashup/java/xdocs/restyservices.html ============================================================================== --- (empty file) +++ trunk/mashup/java/xdocs/restyservices.html Sun Jan 27 02:07:13 2008 @@ -0,0 +1,170 @@ +<!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 http-equiv="content-type" content="" /> + <title>Writing RESTy services</title> + + + <link href="styles.css" rel="stylesheet" type="text/css" media="all" /> + +</head> + + +<body lang="EN-US"> + +<div id="main-content"> +<h1>Writing RESTy services</h1> + +<p>The Mashup Server helps you write RESTy services with relative +ease. +This is facilitated by the use of the httpMethod and the +httpLocation annotations. As theres names imple the httpMethod is used +to specify the HTTP method to be used and the httpLocation annotation +specifies how the parameters can be sent in the request URI. These two +annotation helps you build truly RESTy mashups. You can have a look at +the RESTSample that ships as a sample with the WSO2 Mashup Server for +usage of these annotations.</p> + +<br /> + +<h2 id="inputTypes">httpMethod annotation</h2> + +<br /> + +The httpMethod annotation helps you speficy the HTTP Method that the +operation will be exposed under. Supported HTTP methods are GET, POST, +PUT and DELETE.<br /> +<br /> + +<p class="code">exposeViaGET.httpMethod="GET";<br /> +function exposeViaGET() {<br /> + // get something<br /> +}<br /> +<br /> +exposeViaPOST.httpMethod="POST";<br /> +function exposeViaPOST() {<br /> + // post something<br /> +}<br /> +<br /> +exposeViaPUT.httpMethod="PUT";<br /> +function exposeViaPUT() {<br /> + // put something<br /> +}<br /> +<br /> +exposeViaDELETE.httpMethod="DELETE";<br /> +function exposeViaDELETE() {<br /> + // delete something<br /> +}</p> +<br /> +If the httpMethod is not specified the operation is +exposed under a default HTTP method. The defaulting rule is as follows,<br /> + +<br /> + +1. If the operation is marked as safe using the {function}.safe +annotaion the HTTP method would default to GET (the .safe annotation +defaults to false unless explicitly set).<br /> + +<p class="code">defaultsToGET.safe = true;<br /> + +function defaultsToGET() {<br /> + + // returns something<br /> + +}<br /> + +</p> + +2. If the operation is marked as not safe the HTTP method would default +to POST.<br /> + +<p class="code">function defaultsToPOST() {<br /> + + // do something<br /> + +}</p> +<br /> + +<h2 id="inputTypes">httpLocation annotation</h2> + +<br /> +The +httpLocation annotation helps you take control of the URI and expose +this operation under a logical URI. It does this by specifying a +pattern +for serializing input parameters of the function in the request +URI. Curly braces are +used to specify the name of a input parameter, which determines where +the instance data of that parameter will be located +in the path component of the request URI. In the stubs the curly +brace-enclosed name will be replaced with instance data in +constructing the path component. Remaining input instance data (not +specified by<span style="font-family: monospace;"> httpLocation annotation</span><code></code>) +will be serialized +into the query string portion of the URI. In order for the httpLocation +annotation to be effective you have to use it in conjuction with +inputTypes annotation (The server needs to be aware of how to build the +payload from the request URI and the inputTypes annotation makes this +possible). <br /> +<br /> +The following example shows the use of httpMethod and httpLocation annotations. You can try the service out on your local Mashup Server. Its shipped as the RESTSample.<br /> +<br /> +<p class="code">getWeather.safe = true;<br /> +getWeather.httpMethod = "GET";<br /> +getWeather.httpLocation = "weather/{city}";<br /> +getWeather.inputTypes = "string";<br /> +function getWeather(city){<br /> +var details = session.get(city);<br /> +// return whether details of city<br /> +// for e.g to get the weather details of colombo you need to perform a +GET on http://localhost:7762/services/samples/RESTSample/weather/colombo<br /> +}<br /> +<br /> +POSTWeather.httpMethod = "POST";<br /> +POSTWeather.httpLocation = "weather/{city}";<br /> +POSTWeather.inputTypes = {"city" : "string",<br /> +"weatherDetails" : "string"};<br /> +function POSTWeather(city, weatherDetails){<br /> +// add the weather details of city<br /> +// for e.g to add weather details of colombo you need to perform a POST +on http://localhost:7762/services/samples/RESTSample/weather/colombo +with the following payload<br /> +//<POSTWeather><br /> +// <city>colombo</city><br /> +// <weatherDetails>30</weatherDetails><br /> +//</POSTWeather><br /> +}<br /> +<br /> +DeleteWeather.httpMethod = "DELETE";<br /> +DeleteWeather.httpLocation = "weather/{city}";<br /> +DeleteWeather.inputTypes = "string";<br /> +function DeleteWeather(city){<br /> +// delete the weather details of city<br /> +// for e.g to delete the weather details of colombo you need to perform +a DELETE on +http://localhost:7762/services/samples/RESTSample/weather/colombo<br /> +}<br /> +<br /> +PUTWeather.httpMethod = "PUT";<br /> +PUTWeather.httpLocation = "weather/{city}";<br /> +PUTWeather.inputTypes = {"city" : "string",<br /> +"weatherDetails" : "string"};<br /> +function PUTWeather(city, weatherDetails){<br /> +// update the weather details of city<br /> +// for e.g to update the weather details of colombo you need to perform +a PUT on +http://localhost:7762/services/samples/RESTSample/weather/colombo with +the following payload<br /> +//<PUTWeather><br /> +// <city>colombo</city><br /> +// <weatherDetails>35</weatherDetails><br /> +//</PUTWeather><br /> +}</p> + +</div> + +<p>© WSO2 Inc.</p> + +</body> +</html> _______________________________________________ Mashup-dev mailing list [email protected] http://www.wso2.org/cgi-bin/mailman/listinfo/mashup-dev
