Simple REST Service
This tutorial describes how to create a simple
RESTful
web service.
In this tutorial we will implement a simple service that creates a PNG
image displaying text of a specified font size.
As a RESTful service maintains no state between invocations, the request
must contain all information needed to create the PNG image.
The information required by the service is encoded as query parameters
on the activating URL and is provided with each invocation:
http://localhost:8080/simplerest/Text2PNG?text=Hello%20World&fontsize=20
| text |
Text to be rendered in the PNG image (as URL escaped text) |
(Required) |
| fontsize |
Font size in pixels |
(Optional) |
Step 1
In the first step we create a new module directory.
Follow the steps in the
Manual Module Creation
tutorial
to create a module directory called SimpleREST
and using the following for the module.xml file and register
this new module with the frontend fulcrum.
<module>
<identity>
<uri>urn:simple-rest</uri>
<version>0.1.0</version>
</identity>
<info>
<name>Simple REST</name>
<description>Implements REST services</description>
<type>application</type>
</info>
<export>
<uri>
<match>ffcpl:/simplerest/Text2PNG.*</match>
</uri>
<class />
</export>
<rewrite>
<rule>
<match>ffcpl:/simplerest/Text2PNG(.*)</match>
<to>active:dpml+operand@ffcpl:/text2png.idoc$1</to>
</rule>
</rewrite>
<mapping>
<this>
<match>ffcpl:/.*</match>
</this>
<import>
<uri>urn:org:ten60:netkernel:ext:dpml</uri>
</import>
<import>
<uri>urn:org:ten60:util:image</uri>
</import>
</mapping>
</module>
Step 2
Create the file text2png.idoc in the module located
in [install]/simpleREST/ and copy / paste the following DPML program
into that file:
<idoc>
<seq>
<comment>
**************
Test to see if any parameters were passed
to the service.
If parameters are provided, run the service.
If not, return an HTML page with instructions.
**************
</comment>
<if>
<cond>
<instr>
<type>exists</type>
<operand>this:param:param</operand>
<target>this:cond</target>
</instr>
</cond>
<then>
<comment>
**************
Transform the "param" argument into a Text2PNG
parameter document using an XSLT transform.
**************
</comment>
<instr>
<type>xslt</type>
<operand>this:param:param</operand>
<operator>ffcpl:/convertParameters.xsl</operator>
<target>var:Text2PNG</target>
</instr>
<comment>
**************
Invoke the Text2PNG accessor with the text referenced by xpointer
and the newly created Text2PNG specification doc.
**************
</comment>
<instr>
<type>imageText2PNG</type>
<operand>this:param:param#xpointer(/nvp/text)</operand>
<operator>var:Text2PNG</operator>
<target>this:response</target>
</instr>
</then>
<else>
<comment>
**************
If we don't receive the "param"
argument issue an HTML service description.
**************
</comment>
<instr>
<type>copy</type>
<operand>ffcpl:/htmlpage.xml</operand>
<target>this:response</target>
</instr>
<instr>
<type>cast</type>
<operand>this:response</operand>
<operator>
<cast>
<mimetype>text/html</mimetype>
</cast>
</operator>
<target>this:response</target>
</instr>
</else>
</if>
</seq>
</idoc>
Step 3
Create the file text2png.idoc in the module located
in [install]/simpleREST/ and copy / paste the following DPML program
into that file:
We have to convert an XML document that looks like this:
<nvp>
<text>Hello World</text>
<fontsize>40</fontsize>
</nvp>
To this:
<text2PNG>
<fontsize>40</fontsize>
</text2PNG>
And also handle the case of a missing parameter (the fontsize is optional).
If the parameter is missing we will use 12 pixels as the default.
This is accomplished with the following XSLT stylesheet:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="xml" />
<xsl:template match="/nvp">
<text2PNG>
<fontsize>
<!---->
<xsl:choose>
<xsl:when test="fontsize">
<xsl:value-of select="fontsize" />
</xsl:when>
<xsl:otherwise>12</xsl:otherwise>
</xsl:choose>
</fontsize>
</text2PNG>
</xsl:template>
</xsl:stylesheet>
Step 3
Create the file text2png.idoc in the module located
in [install]/simpleREST/ and copy / paste the following DPML program
into that file:
<html>
<body>
<h2>Text2PNG Service Specification</h2>
<p>
This service generates a PNG bitmap image of a supplied text string.
It supports an optional fontsize argument. The service is exported
with a URL /trailmap/service/Text2PNG. So an example request on
the interface would look like...
</p>
<p>
<code>
http://localhost:8080/simplerest/Text2PNG?text=Hello%20World&fontsize=20
</code>
<ul>
<li>
<b>text</b> is the URL escaped text string to render
</li>
<li>
<b>fontsize</b> is the optional font size to render the text with
</li>
</ul>
The service will support either GET or POST encoded form data requests.
</p>
<p>
If no query parameters are supplied this service interface description is served.
</p>
</body>
</html>
Power User REST
This example allows the default settings of the HTTP bridge to take care of parameter processing.
For REST services that require access to
the full range of information provided in the HTTP request - such as VERB, HTTP Headers, etc etc
you can provide an ffcpl:/etc/HTTPBridgeConfig.xml resource containing a declarative
description of how to process the HTTP request. For details read the HTTP Bridge Guide.
RESTful Path Processing
The
Address Book tutorial shows a complete database backed application
and shows how to write RESTful services with REST path processing.
Tutorial Introduction
Fundamentals
Practicalites
Web
