RESTful requests with TurmericSOA

Posted: December 12, 2011 in REST, SOA, Turmeric

This time I’m gonna write about how to play in Turmeric with RESTful requests.

First of all we need a deployed service, any, in our Web Server, in my case Jetty 7, indeed, I use jetty-turmeric , this is a customized Jetty for running our Turmeric engine and deploying services in one or two simple steps…basically for simple but comprehensive tests.

The service I use is a sample EchoService, already included under the Turmeric Runtime module. So, under our WebServer/webapp folder we have a folder called example-echoservice. example-echoservice


|----META-INF
|----WEB-INF
        |-----classes
        |-----lib
               |-----ExampleEchoServiceV1-1.0.1.0-SNAPSHOT.jar
               |-----ExampleEchoServiceV1Impl-1.0.1.0-SNAPSHOT.jar
        |-----web.xml
|----index.html

Our web.xml deployment file should look like this:


<web-app
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd"
metadata-complete="false"
version="2.5">
<display-name>Spfservlet Test</display-name>
<servlet>
<description>ExampleEchoServiceV1</description>
<display-name>ExampleEchoServiceV1</display-name>
<servlet-name>ExampleEchoServiceV1</servlet-name>
<servlet-class>org.ebayopensource.turmeric.runtime.spf.pipeline.SPFServlet</servlet-class>
<load-on-startup>1</load-on-startup>
<init-param>
<param-name>SOA_SERVICE_NAME</param-name>
<param-value>ExampleEchoServiceV1</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>ExampleEchoServiceV1</servlet-name>
<url-pattern>/ExampleEchoServiceV1</url-pattern>
</servlet-mapping>
</web-app>

The included Echo sample is ready to be deployed, so after copy/paste this project under our jetty-turmeric, the service could be achieved through: http://localhost:8080/example-echoservice/ExampleEchoServiceV1?echo&echoText=Hello and the response should be similar as:

<echoResponse>
<ack>Success</ack>
<output>HelloGuest</output>
</echoResponse>

Now, let’s review the main config file in this scenario, that is the ServiceConfig.xml under the ExampleEchoServiceV1Impl.jar By default it comes with a very simple an basic turmeric configuration:


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<service-config xmlns="http://www.ebayopensource.org/turmeric/common/config">
<service-impl-class-name>org.ebayopensource.turmeric.example.v1.services.echoservice.impl.ExampleEchoServiceV1Impl</service-impl-class-name>
<service-interface-class-name>org.ebayopensource.turmeric.example.v1.services.echoservice.ExampleEchoServiceV1</service-interface-class-name>
<service-instance-config>
<provider-options>
<header-mapping-options>
<option name="X-TURMERIC-OPERATION-NAME">queryop</option>
<option name="X-TURMERIC-RESPONSE-DATA-FORMAT">query[format]</option>
</header-mapping-options>
</provider-options>

<protocol-processor version="1.1" name="SOAP11">
<indicator>
<transport-header name="X-TURMERIC-MESSAGE-PROTOCOL">SOAP11</transport-header>
</indicator>
<class-name>org.ebayopensource.turmeric.runtime.spf.impl.protocolprocessor.soap.ServerSOAPProtocolProcessor</class-name>
</protocol-processor>
<protocol-processor version="1.2" name="SOAP12">
<indicator>
<transport-header name="X-TURMERIC-MESSAGE-PROTOCOL">SOAP12</transport-header>
</indicator>
<class-name>org.ebayopensource.turmeric.runtime.spf.impl.protocolprocessor.soap.ServerSOAPProtocolProcessor</class-name>
</protocol-processor>
</service-instance-config>
</service-config>
<pre>

We have three main tag blocks here, lets forget the protocol-processor for now, they are SOAP related protocols, not usefull in our REST scenario…

Then, according this Turmeric wiki page, there some required parameters when we make a service call, but if we recall our endpoint (http://localhost:8080/example-echoservice/ExampleEchoServiceV1?echo&echoText=Hello) seems we forgot the X-TURMERIC-OPERATION-NAME. That is the purpose of queryop value in header-mapping-options, it automatically retrieves the first request parameter as the operation name, so we could replace an original and longer URL request http://localhost:8080/example-echoservice/ExampleEchoServiceV1?X-TURMERIC-OPERATION-NAME=echo&echoText=Hello by http://localhost:8080/example-echoservice/ExampleEchoServiceV1?echo&echoText=Hello.

In addition, one of our followers wants to achieve the service through this endpoint instead: http://localhost:8080/example-echoservice/ExampleEchoServiceV1/echo/Hello                <— pay attention, there is no question mark to specify the parameters

So, there are two simple steps you want to perform, first of all you need to update your deployment descriptor file for a propper intrepretation of your new URL, that is adding a wild card in your Servlet Mapping:

<servlet-mapping>
<servlet-name>ExampleEchoServiceV1</servlet-name>
<url-pattern>/ExampleEchoServiceV1/*</url-pattern>
</servlet-mapping>

Next step is to update the ServiceConfig.xml in order to read the latest word in our URL word as the echoText parameter, this tag section must be added following the header-mapping-options


<request-params-mapping>
<operation name="echo">
<option name="echoText">path[3]</option>
</operation>
</request-params-mapping>

That will read the 3rd expression in our URL

Please surf here for more info about URL mapping under REST request.

Also you can specify a pipeline process into the ServiceConfig.xml to provide Authentication, Rate Limiter capabilities or maybe custom handler to improve your service governance, but this  deserves another post 🙂

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s