Home
ESB
Monitor
Registry
SOAP Client
SOA Model
Support
Downloads
About
requires version 3.0.0 or higher

REST Router Quickstart Tutorial

To run the example do the following:

  1. Download Membrane Router version 3.0.0 or above.

  2. Execute router.bat in the MEMBRANE_HOME/examples/quickstart-rest directory.

    3. The script router.bat will start the router and load the proxies.xml file.

    				<proxies>
					<serviceProxy name="names" port="2000">
						<target host="thomas-bayer.com" port="80" />
					</serviceProxy>				
				</proxies>
    Listing 1: proxies.xml

    Thats all to setup a reverse proxy. Pretty easy isn't it? The serviceProxy will listen at port 2000 at the localhost for HTTP messages. If it receives a message it will be forwarding 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.

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

    4. 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 regexUrlRewriter to the serviceProxy. Wrap it with a request element. By using the request element the interceptor will only be called for the request.

    3. 						<proxies>
							<serviceProxy name="names" port="2000">
								<request>
									<regExUrlRewriter>
										<mapping regex="/names/(.*)" uri="/restnames/name\.groovy\?name=$1" />
									</regExUrlRewriter>		
								</request>
								<target host="thomas-bayer.com" port="80" />
							</serviceProxy>						
						</proxies>
    Listing 3: RegExUrlRewriter

  3. Restart the router.

  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.           <proxies>
            <serviceProxy name="names" port="2000">
              <request>
                <regExUrlRewriter>
                  <mapping regex="/names/(.*)" uri="/restnames/name\.groovy\?name=$1" />
                </regExUrlRewriter>		
              </request>
              <statisticsCSV file="log.csv" />								
              <target host="thomas-bayer.com" port="80" />
            </serviceProxy>						
          </proxies>
    Listing 4: StatisticsCSV Interceptor

  2. Restart the router.

  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.

    5. http://localhost:2000/names/Pia

Applying A XSLT Transformation to Requests and Responses

  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 request element. By using the request element the transformation will only be applied to the response.

    2.           <proxies>
            <serviceProxy name="names" port="2000">
              <request>
                <regExUrlRewriter>
                  <mapping regex="/names/(.*)" uri="/restnames/name\.groovy\?name=$1" />
                </regExUrlRewriter>		
              </request>
              <statisticsCSV file="log.csv" />
              <response>
                <transform xslt="restnames.xsl" />
              </response>
              <target host="thomas-bayer.com" port="80" />
            </serviceProxy>						
          </proxies>
    Listing 5: Transform Interceptor

  2. Restart the router.

  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 Regulare 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.           <proxies>
            <serviceProxy name="names" port="2000">
              <request>
                <regExUrlRewriter>
                  <mapping regex="/names/(.*)" uri="/restnames/name\.groovy\?name=$1" />
                </regExUrlRewriter>		
              </request>
              <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>
          </proxies>
    Listing 7: RegExReplacer

  2. Restart the router.

  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.         <proxies>
          <serviceProxy name="names" port="2000">
            <request>
              <regExUrlRewriter>
                <mapping regex="/names/(.*)" uri="/restnames/name\.groovy\?name=$1" />
              </regExUrlRewriter>		
            </request>
            <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>	
        </proxies>
    Listing 9: Service Proxy for Admin Console

  3. Restart the router.

  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
    Figure 1: 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
    Figure 2: List of Interceptors Registered by serviceProxy Called names

Securing with HTTP Basic Authentication

  1. Add a BasicAuthentication interceptor to the serviceProxy called Consol.

    2.           <proxies>
            <serviceProxy name="names" port="2000">
              <request>
                <regExUrlRewriter>
                  <mapping regex="/names/(.*)" uri="/restnames/name\.groovy\?name=$1" />
                </regExUrlRewriter>		
              </request>
              <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>	
          </proxies>
    Listing 10: BasicAuthentication Interceptor

  2. Restart the router.

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

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