Go to new doc!
HomeAPI GatewaySOA ModelSupportDownloadsAbout

+49 228 5552576-0


info@predic8.com

REST Router Quickstart Tutorial

Help needed?

Do you need any help for this tutorial. Then contact us using the Membrane Google Group or send an email to membrane@predic8.com.

In this tutorial you will create a service proxy for a REST API and add additional functionality like URL rewriting, logging and transformation.

To run the example:

  1. download Membrane Service Proxy version 4.0.18 or above and unzip it.

  2. open a command prompt and change to the installation folder of the unzipped archive.

  3. change to the subfolder examples/quickstart-rest

  4. execute service-proxy.bat or service-proxy.sh. Make sure you are in the examples/quickstart-rest folder.

    5. The script service-proxy.bat will start the router and load the proxies.xml file.

                <spring:beans xmlns="http://membrane-soa.org/proxies/1/"
            xmlns:spring="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
            http://membrane-soa.org/proxies/1/ http://membrane-soa.org/schemas/proxies-1.xsd">

              <router>

                <serviceProxy name="names" port="2000">
                  <target host="thomas-bayer.com" port="80" />
                </serviceProxy>

              </router>

            </spring:beans>
    Listing 1: proxies.xml

    That's all to setup a reverse proxy. Pretty easy isn't it? The serviceProxy will listen at port 2000 for HTTP messages. If it receives a message it will be forwarded to thomas-bayer.com at port 80.

    Next we will use the RESTNames resources that offer information about firstnames and their distribution in different countries.

  5. Now take a look at the REST resource at the following URL.

    6. http://localhost:2000/restnames/name.groovy?name=Pia 

                      <restnames>
                  <nameinfo>
                  <name>Pia</name>
                  <countries>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Italy">Italy</country>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Spain">Spain</country>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Belgium">Belgium</country>

                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Netherlands">Netherlands</country>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Frisia">Frisia</country>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Germany">Germany</country>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Austria">Austria</country>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Swiss">Swiss</country>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Denmark">Denmark</country>

                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Norway">Norway</country>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Sweden">Sweden</country>
                  <country href="http://thomas-bayer.com:80/restnames/namesincountry.groovy?country=Finland">Finland</country>
                  </countries>
                  <gender>female first name</gender>
                  <male>false</male>

                  <female>true</female>
                  </nameinfo>
                  </restnames>
    Listing 2: Restnames

    In the response you can see a list of countries where the name Pia is used often.

Rewriting URLs

  1. Open the proxies.xml file in an editor.

  2. Add a rewriter to the serviceProxy.

    3.                   [...]
                  <serviceProxy name="names" port="2000">
                    <path isRegExp="true">/(rest)?names.*</path>
                    <rewriter>
                      <map from="^/names/(.*)" to="/restnames/name\.groovy\?name=$1" />
                    </rewriter>
                    <target host="thomas-bayer.com" port="80" />
                  </serviceProxy>
                  [...]
    Listing 3: Rewriter

  3. Save the proxies.xml file and Membrane will detect the modification and automatically reload.

  4. Open the following URL in your browser: http://localhost:2000/names/Pia

Logging

  1. Add a statisticsCSV interceptor to the serviceProxy and specify a location for the logfile.

    2.                  <serviceProxy name="names" port="2000">
                   <path isRegExp="true">/(rest)?names.*</path>
                   <rewriter>
                     <map from="^/names/(.*)" to="/restnames/name\.groovy\?name=$1" />
                   </rewriter>
                   <statisticsCSV file="log.csv" />
                   <target host="thomas-bayer.com" port="80" />
                 </serviceProxy>
    Listing 4: StatisticsCSV Interceptor

  2. Save the proxies.xml file to trigger a reload of Membrane.

  3. Open the following URL in your browser: http://localhost:2000/names/Pia

  4. Take a look at the log.csv file generated in the rest-quickstart directory.

Applying A XSLT Transformation

  1. Add a transform interceptor to the serviceProxy and specify the XSLT file that will be applied to requests and responses. Wrap the transformer with a response element. By using the response element the transformation will only be applied to the response.

    2.              <serviceProxy name="names" port="2000">
               <path isRegExp="true">/(rest)?names.*</path>
               <rewriter>
                 <map from="/names/(.*)" to="/restnames/name\.groovy\?name=$1" />
               </rewriter>
               <statisticsCSV file="log.csv" />
               <response>
                 <transform xslt="restnames.xsl" />
               </response>
               <target host="thomas-bayer.com" port="80" />
             </serviceProxy>
    Listing 5: Transform Interceptor

  2. Save the proxies.xml file to trigger a reload.

  3. Open the following URL in your browser: http://localhost:2000/names/Pia

    4. The transformed response will look like this:

                  <restnames>
                <name>Pia</name>
                <countries>Italy, Spain, Belgium, Netherlands, Frisia, Germany, Austria, Swiss, Denmark, Norway, Sweden, Finland,</countries>
                <gender>female first name</gender>
              </restnames>
    Listing 6: Transformed Response

Using Regular Expressions To Replace Parts Of The Content

  1. Add a regExReplacer to the serviceProxy. Place it within the response element and befor the transformer interceptor. Specify the regex to match against the content and the string that will be used to replace the matched substrings.

    2.              <serviceProxy name="names" port="2000">
               <path isRegExp="true">/(rest)?names.*</path>
               <rewriter>
                 <map from="^/names/(.*)" to="/restnames/name\.groovy\?name=$1" />
               </rewriter>
               <statisticsCSV file="log.csv" />
               <response>
                 <regExReplacer regex="\s*,\s*&lt;" replace="&lt;" />
                 <transform xslt="restnames.xsl" />
               </response>
               <target host="thomas-bayer.com" port="80" />
             </serviceProxy>
    Listing 7: RegExReplacer

  2. Save the proxies.xml file.

  3. Open the following URL in your browser: http://localhost:2000/names/Pia

    4. Notice the deleted comma at the end of the list.

                  <restnames>
                <name>Pia</name>
                <countries>Italy, Spain, Belgium, Netherlands, Frisia, Germany, Austria, Swiss, Denmark, Norway, Sweden, Finland</countries>
                <gender>female first name</gender>
              </restnames>
    Listing 8: Replaced Response

Administration Console

Membrane Router provides a Web console that allows you to view and list proxy definitions.

  1. Open the proxies.xml file in an editor.

  2. Add an additional serviceProxy containing an adminConsole element.

    3.             <spring:beans xmlns="http://membrane-soa.org/proxies/1/"
            xmlns:spring="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
            http://membrane-soa.org/proxies/1/ http://membrane-soa.org/schemas/proxies-1.xsd">

            <router>

            <serviceProxy name="names" port="2000">
            <path isRegExp="true">/(rest)?names.*</path>
            <rewriter>
            <map from="^/names/(.*)" to="/restnames/name\.groovy\?name=$1" />
            </rewriter>
            <statisticsCSV file="log.csv" />
            <response>
            <regExReplacer regex="\s*,\s*&lt;" replace="&lt;" />
            <transform xslt="restnames.xsl" />
            </response>
            <target host="thomas-bayer.com" port="80" />
            </serviceProxy>

            <serviceProxy name="Console" port="9000">
            <adminConsole />
            </serviceProxy>

            </router>

            </spring:beans>
    Listing 9: Service Proxy for Admin Console

  3. Save the proxies.xml file.

  4. Open the following URL in your browser: http://localhost:9000/admin

  5. Now you will see a list containing the service proxies you have defined in the proxies.xml file.

    6. AdminConsole

    Figure1: AdminConsole

  6. Click on the link names.

    7. You will see all interceptors you have registered before.

    List of Interceptors Registered by serviceProxy Called names

    Figure2: List of Interceptors Registered by serviceProxy Called names

Securing with HTTP Basic Authentication

  1. Add a basicAuthentication interceptor to the serviceProxy named Console.

    2.                 <spring:beans xmlns="http://membrane-soa.org/proxies/1/"
                xmlns:spring="http://www.springframework.org/schema/beans"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
                http://membrane-soa.org/proxies/1/ http://membrane-soa.org/schemas/proxies-1.xsd">

                <router>

                <serviceProxy name="names" port="2000">
                <path isRegExp="true">/(rest)?names.*</path>
                <rewriter>
                <map from="/names/(.*)" to="/restnames/name\.groovy\?name=$1" />
                </rewriter>
                <statisticsCSV file="log.csv" />
                <response>
                <regExReplacer regex="\s*,\s*&lt;" replace="&lt;" />
                <transform xslt="restnames.xsl" />
                </response>
                <target host="thomas-bayer.com" port="80" />
                </serviceProxy>

                <serviceProxy name="Console" port="9000">
                <basicAuthentication>
                <user name="alice" password="membrane" />
                </basicAuthentication>
                <adminConsole />
                </serviceProxy>

                </router>

                </spring:beans>
    Listing 10: BasicAuthentication Interceptor

  2. Save the proxies.xml file.

  3. Open the following URL in your browser: http://localhost:9000/admin

    4. Login with the username alice and the password membrane.