Tuscany SCA Native - REST Extension
This document describes the deployment and use of the REST
binding support in the Apache Tuscany SCA Native runtime.
The Tuscany REST extension allows SCA services and references to be invoked
via HTTP REST calls
The following samples demonstrate use of the REST extension:
System Requirements
In order to install and use the Tuscany SCA REST Extension there are some
extra requirements in addition to the Tuscany
SCA requirements:
| Software |
Download Link |
| Apache HTTPD version 2.2 |
http://httpd.apache.org
Please download and follow the installation instructions. This is required
for building the REST Service extension and for hosting and running REST services.
|
| libcurl version 7.15 or higher |
http://curl.haxx.se/download.html
Please download and follow the installation instructions. This is required
for building the REST Reference extension and for calling REST references.
On Windows, the extension was developed and tested against the "Win32 - MSVC 7.15.1 devel"
library provided by Chris Drake. On Linux the libcurl libraries were built from
the 7.16.1 source. On Mac OS X the library was downloaded, built and installed via the
standard "port" command.
|
Installing the Tuscany SCA REST Extension
Getting the Tuscany SCA REST Extension working with the binary release on Linux and Mac OS X
- Follow the deployment steps below to ensure the HTTPD server
invokes Tuscany when it receives an appropriate HTTP request
- Ensure the libcurl and HTTPD libraries are available on the LD_LIBRARY_PATH environment variable on Linux and
the DYLD_LIBRARY_PATH environment variable on Mac OS X
Getting the Tuscany SCA REST Extension working with the source release on Linux and Mac OS X
- You will need the Tuscany SCA and SDO libraries - follow the instructions
here to build the SCA libraries and default extensions
- The following environment variables are required:
- TUSCANY_SCACPP=<path to built Tuscany SCA>
- TUSCANY_SDOCPP=<path to installed Tuscany SDO>
- APR_INCLUDE=<path to APR includes>
- HTTPD_INCLUDE=<path to HTTPD includes>
Note: If you are using a default installation of HTTPD these are usually:
APR_INCLUDE=/usr/include/apr-1
HTTPD_INCLUDE=/usr/include/httpd
- CURL_INCLUDE=<path to libcurl includes>
- CURL_LIB<path to libcurl libraries>
Note: If you are using a default installation of libcurl these are usually:
CURL_INCLUDE=/usr/include/curl
CURL_LIB=/usr/lib
- Build the REST source only with the following command sequence:
- cd <tuscany_sca_install_dir>
- ./configure --prefix=$TUSCANY_SCACPP --enable-restbinding --enable-cpp=no --enable-wsbinding=no
- make
- make install
NOTE: If you don't provide a --prefix configure option, it will by default install into
/usr/local/tuscany/sca
Getting the Tuscany SCA REST Extension working with the binary release on Windows
- Follow the deployment steps below to ensure the HTTPD server
invokes Tuscany when it receives an appropriate HTTP request
- Ensure the libcurl and HTTPD libraries are available on the PATH environment variable
Getting the Tuscany SCA REST Extension working with the source release on Windows
- Unzip the supplied source zip file
- The following environment variables are required:
- TUSCANY_SCACPP=<path to built Tuscany SCA>
- TUSCANY_SDOCPP=<path to installed Tuscany SDO>
- HTTPD_HOME=<path to installed HTTPD server>
- LIBCURL_HOME=<path to installed libcurl libraries>
- You must have set up the environment for Microsoft Visual C++ tools. The build command
will call vcvars32 to set the environment. Ensure the directory containing this is on your path.
This will be where you installed the compiler.
- Build the source:
- cd <to where you unzipped the source>
- build
This will build all the projects and put the required output into the 'deploy' directory
Alternatively, open the workspace at <tuscany_sca_install_dir>/projects/tuscany_sca/tuscany_sca.dsw
in Visual Studio 6 or at at <tuscany_sca_install_dir>/projectsvc7/tuscany_sca/tuscany_sca.sln
in Visual Studio 7.1 - you can build projects individually
or build the samples to rebuild all the projects
Deploying the Tuscany REST Service extension to the HTTPD server
The following samples demonstrate use of the REST extension:
Each of these samples generate a set of configuration files for the HTTPD server. Use the startserver
script that comes with each sample to generate the files and start the server with the REST Service
extension enabled. The instructions below detail the information that is provided in these configuration
files.
- On Windows, load the sca_rest_module into HTTPD by adding the following line to the conf/httpd.conf file:
LoadModule sca_rest_module <path to installed Tuscany SCA>/extensions/rest/service/bin/tuscany_sca_mod_rest.dll
On Linux, use the following line:
LoadModule sca_rest_module <path to installed Tuscany SCA>/extensions/rest/service/lib/libtuscany_sca_mod_rest.so
On Mac OS X, use the following line:
LoadModule sca_rest_module <path to installed Tuscany SCA>/extensions/rest/service/lib/libtuscany_sca_mod_rest.dylib
- Set a TuscanyHome directive to the installation of Tuscany SCA Native:
TuscanyHome <path to installed Tuscany SCA>
- Create a Location directive for the URL to be used and set the sca_rest_module as the handler to
be invoked when requests for the location are received. Also set the TuscanyRoot directive for
this Location, set to the location of the SCA application to be invoked:
<Location /rest>
SetHandler sca_rest_module
TuscanyRoot <path to installed Tuscany SCA>/samples/RestCalculator/deploy/
</Location>
The above example will mean that calls to http://myserver/rest will be handled by Tuscany SCA Native
and configured to invoke the RestCalculator sample application.
Tuscany REST Extension Resource Pattern
If the SCA service or reference uses an <interface.rest> interface, CRUD
(Create, Retrieve, Update, Delete) methods are mapped to HTTP verbs to access resource
representations as follows:
- uri = create(resource)
HTTP POST <binding-uri> + an XML element representing the resource to create
Returns Location header containing the uri of the created resource
- resource = retrieve()
HTTP GET <binding-uri>
Returns an XML element representing the REST resource
- resource = retrieve(uri, parm-value-1, parm-value-n)
HTTP GET uri/parm-value-1/parm-value-n
or if uri ends with a '?':
HTTP GET uri?parm-name-1=parm-value1&parm-name-n=parm-value-n
Returns an XML element representing the REST resource
- update(resource)
HTTP PUT <binding-uri> + an XML element representing the updated resource
- update(uri, parm-1, parm-n, resource)
HTTP PUT uri/parm-value-1/parm-value-n + an XML element representing the updated resource
or if uri ends with a '?':
HTTP PUT uri?parm-name-1=parm-value1&parm-name-n=parm-value-n + an XML element representing the updated resource
- delete()
HTTP DELETE <binding-uri>
- delete(uri, parm-1, parm-n)
HTTP DELETE uri/parm-value-1/parm-value-n
or if uri ends with a '?':
HTTP DELETE uri?parm-name-1=parm-value1&parm-name-n=parm-value-n
In this mode, HTTP return codes are used almost as described in the Atom spec. Also
GET returns etags with the retrieved resource representations to help caching by clients.
Tuscany REST Extension RPC Pattern
If the SCA service/reference does not use an <interface.rest> interface, then this is
not a real REST pattern, we simply flow method calls over XML / HTTP as follows:
- result = method-abc(parm-1, parm-n)
- if single input parameter of complex type:
HTTP POST <binding-uri>/method-abc + XML element representing the complex parameter
- or if multiple parameters including parameters of complex types:
HTTP POST <binding-uri>/method-abc + Mime multipart/form-data body containing one parameter per part
- or if multiple parameters all of simple types:
HTTP GET <binding-uri>/method-abc?parm-1-name=parm-1-value&parm-n-name=parm-n-value
Returns an XML element representing the result