Using DataPower with WSRR and REST services, Part 1: Registering, exposing, and invoking a REST service with a sample client

You may already be using the policy integration between WebSphere DataPower (DataPower) V5 and WebSphere Service Registry and Repository (WSRR) V8 to express your business intent for your services in the form of policies. Perhaps you are using DataPower to do dynamic lookup of web service endpoints stored in WSRR for WSDL-based services. This article shows you how to use new capabilities in DataPower V6 and WSRR V8.0.0.2 to dynamically look up endpoint URLs of REST services that are registered in WSRR. Policies authored and stored in WSRR and enforced by DataPower have also been enriched with new capabilities.

Share:

Ainhoa Larumbe (ainhoa.larumbe@uk.ibm.com), Software Engineer, IBM

Photo of Ainhoa LarumbeAinhoa Larumbe is a Software Developer on the WebSphere Service Registry and Repository Development team at the IBM Hursley Development Lab in the U.K. She has six years of IT experience in software development. Her areas of expertise include AJAX, Java, JavaScript, and XML development, and web UI test and design. You can contact Ainhoa at ainhoa.larumbe@uk.ibm.com.



David Seager (seager@uk.ibm.com), Software Developer, IBM

Photo of David J. SeagerDavid J. Seager is a Software Developer on the WebSphere Service Registry and Repository Development team at the IBM Hursley Development Lab in the U.K. He has 15 years of experience in middleware development at IBM, and has Masters degrees in Software Engineering and Physics, both from Oxford University in the UK. His areas of expertise include AJAX, Java, JavaScript, WebSphere Application Server, and web UI design. David has authored several developerWorks articles, co-authored the IBM Redbook CICS Transaction Gateway V5: The WebSphere Connector for CICS (SG24-6133), and authored two IBM Redpapers: WebSphere Service Registry and Repository Reporting with Business Intelligence and Reporting Tools (BIRT), and Customization and Deployment of WebSphere Service Registry and Repository Business Space Widgets. David maintains the Service Registry Sagacity blog on developerWorks and the Service Registry YouTube channel. You can contact David at seager@uk.ibm.com.



20 November 2013

Introduction

A service registry is the central catalog for services within an organisation. It provides important governance and registration functions, enabling an organisation to keep track of what stage its services are in, who is using them, and policies and other metadata associated with them. IBM® WebSphere® Service Registry and Repository (hereafter called WSRR), IBM's service registry product, gives visibility to services and provides a central place to search for them.

You can use WSRR to author and store policy documents to indicate your business intent, attach them to services stored in WSRR, and have the policies enforced at run time by a policy enforcement point (PEP), such as a WebSphere DataPower Appliance (hereafter called DataPower). These web service mediation policies let you specify an expression, such as that there are more than 500 messages per second, and what happens when the expression is true or false. For example, when the number of messages per second exceeds 500, you can queue messages until the messages per second no longer exceeds 500. In DataPower Firmware V5, you can proxy a web service stored in WSRR and enforce policies attached to the service.

In WSRR V8, you can register REST services, which are services invoked using the HTTP protocol and REST semantics. Such services are also called APIs. You can document the service interface in WSRR, document example invocation messages, and record the URL of the service. Additionally, you can record consumers of a REST service and what other services a REST service may consume.

WSRR V8 Fix Pack 2 (V8.0.0.2) and DataPower V6 add new capabilities on top of WSRR V8 and DataPower V5. DataPower V6 can dynamically look up the endpoint URL of REST-based services that are registered in WSRR. The policies that are authored and stored in WSRR and enforced by DataPower have also been enriched with new capabilities, in a new version of the policy specification called WS-MediationPolicy 1.7.

This article series focuses on the WSRR and DataPower support for WS-MediationPolicy 1.7 and REST services. In this article, you will learn how to expose a REST service registered in WSRR through a proxy in DataPower, and you will use a sample service and client to invoke the service through DataPower.

This article provides a set of sample objects that represents a REST service and shows you how to import them into WSRR so that they make up all the governed objects in the correct state required for a policy to be attached. Then the article shows you how to create a Multi-Protocol Gateway in DataPower that will be subscribed to the REST service in WSRR, and will therefore automatically enforce any policies attached to it. The Multi-Protocol Gateway will route requests to the service URL registered in WSRR.

Future articles in this series will show you how to use policies to enforce service level mediation policies, and use the new features in the WS-MediationPolicy 1.7 spec.

Prerequisites

  • WSRR V8.0.0.2 (or later) with security enabled
  • A WSRR configuration profile deployed and activated as the WSRR Governance Enablement Profile (GEP)
  • WebSphere Business Space installed and configured to work with WSRR, and a business space based on the Operations template
  • WebSphere DataPower V6.0
  • WSRR and DataPower configured to communicate securely, as explained in the developerWorks article Secure integration of WSRR with WebSphere DataPower

You can download a sample REST service and client at the bottom of this article. It is packaged as an EAR file and must be deployed into a WebSphere Application Server instance. You then access a web-based client for the REST service at http://<host>:<port>/CatalogSearch/, where <host> and <port> are the host name and port number of the server. You can deploy the EAR to the WebSphere Application Server instance hosting WSRR. The client lets you set all parameters needed to fully exercise the functionality and is described in the article.

Setting up WSRR

In order to have DataPower automatically subscribe to service updates, you must add configuration items to WSRR, and edit an existing named query. The steps to do this are detailed in Updates to configuration profile required for using WS-MediationPolicy 1.7 in the WSRR information center.

You must create two named queries called SLDFromServiceVersion and ServiceVersionFromSLD. These queries enable DataPower to subscribe to a service version in WSRR, and be notified when any aspect of the service version changes. For more information, see Creating named queries for retrieving policy attachments associated with service versions in the WSRR information center.

You must edit the SLDEndpointsUsingLifecycleState named query to only return internal endpoints in the online state, so that you can use the External classification on endpoints to hide them from DataPower. This option lets you register the DataPower proxy endpoints in WSRR and classify them as External, without DataPower itself finding these endpoints and attempting to route traffic to them. For more information, see Editing the SLDEndpointsUsingLifecycleState named query in the WSRR information center.

Changing the SLDEndpointsUsingLifecycleState named query also affects the behaviour of DataPower for SOAP-based services. Any SOAP service endpoints in WSRR that are consumed by DataPower in a web service proxy must be updated and classified as Internal. Otherwise, the policies attached in WSRR will not be discovered by DataPower after you make this change.

You can also create a new classification for WS-MediationPolicy 1.7 policy expressions. This classification enables WSRR to automatically classify any WS-MediationPolicy 1.7 created with a special Mediation Policy 1.7 classification, which lets you search specifically for 1.7 WS-MediationPolicy policies. This step is optional and not required for the DataPower REST support.

Registering a REST service in WSRR

For the steps to register a REST service, see the tutorial Governing an existing REST service in the WSRR information center. In this tutorial, you register a service called Catalog Search, create version 1.0 of the service using REST, and register two URLs where the service resides.

You can also import the provided .zip file to create the required objects in WSRR, to quickly and easily register the Catalog Search service. This creates a Service Version object that represents the version of the service, including with the supporting objects that represent the endpoint URL where the service runs. To import the zip file:

  1. Ensure that you are logged into the WSRR Web UI.
  2. Change to the Administrator perspective using the Perspective dropdown menu at the top of the page.
  3. Under the Actions dropdown menu, select Import.
  4. Click Browse and navigate to where you have saved catalog_service_export.zip. Double-click the file and then click OK.

Once the import is complete, you will be told that you have successfully imported the Catalog Search object, but you have actually imported all the objects created in the GEP tutorial.

Changing the endpoints in WSRR

Because you are modelling a REST service, the endpoint URL is represented as a REST endpoint object in WSRR. The metadata of this object carries the endpoint URL of the service, and is used by DataPower to determine where to send requests. Therefore you must change the endpoint URL to specify where you deployed the sample REST service. The set of objects that you loaded in from catalog_service_export.zip (or created yourself by following the GEP Tutorial) included a REST endpoint with the endpoint URL of http://CSProductionHost:9443/services/catalog/. You must now change it to point to the correct URL:

  1. Ensure that you are logged into the WSRR Business Space UI and on the Operation space.
  2. On the Overview page in the Search widget, select REST Service Endpoint in the Types dropdown menu and then click Search to show the REST endpoints.
  3. In the Collection widget, click http://CSProductionHost:9443/services/catalog/ (1.0) to open it in the Detail widget.
  4. Click the Pencil icon at the top right of the widget to edit the endpoint.
  5. Change the name and base URL to the location of the Catalog Search EAR. For example: http://djsbpm.hursley.ibm.com:9080/CatalogSearch/. Ensure that you change both the name and the base URL properties, and that you change the entire URL. The sample Catalog Search service uses a context root of /CatalogSearch/.

Because you updated the SLDEndpointsUsingLifecycleState named query to return internal endpoints that are in the online state, you must change the visibility of the endpoint from External to Internal. This Internal classification means that although the endpoint is in production, it is for consumption only by the DataPower Appliance. To register an endpoint for consumption by consumers, then register an endpoint with the external classification and the URL of the DataPower Multi-Protocol Gateway :

  1. Click the Pencil icon next to the Visibility section.
  2. In the Visibility dialog, uncheck External and check Internal.
  3. Click Close. Here is the completed endpoint:
    Completed endpoint for REST service
    Completed endpoint for REST service
  4. Click Finish to save your changes to the endpoint.

If you followed the GEP tutorial, then you created a REST endpoint for a staging environment, put it into the Online state, and classified it as Internal. Because in this article you are not using a WSRR production runtime with DataPower, DataPower will see the staging endpoint and could attempt to route messages to it, which is not desired. Therefore you must put the staging endpoint either offline, or else remove the Internal classification. In the supplied import, the staging endpoint is classified as External, so if you imported the WSRR objects, you do not need to change the staging endpoint. If you followed the GEP tutorial, perform the following steps to take the endpoint offline:

  1. Ensure that you are logged into the WSRR Business Space UI and on the Operation space.
  2. On the Overview page in the Search widget, select REST Service Endpoint in the Types dropdown menu, and then click Search to show the REST endpoints.
  3. In the Collection widget, click http://CSStagingHost:9081/services/catalog (1.0) to open the staging endpoint in the Detail widget.
  4. In the Detail widget, select the Action menu, select Revoke From Use, and then click OK.

The staging endpoint is now in the offline state, and DataPower will not attempt to use the staging endpoint to route traffic to the Catalog Search service.

Creating a Multi-Protocol Gateway

Now that you have the endpoint of your REST service registered in WSRR, you can set up a proxy in DataPower that takes the endpoint from WSRR and routes requests to the real service. This proxy is a Multi-Protocol Gateway in DataPower.

  1. Navigate to the DataPower Control Panel for your domain, and click the Multi-Protocol Gateway icon.
  2. On the Configure Multi-Protocol Gateway page, click Add.
  3. In the Multi-Protocol Gateway Name field, enter a name for your new gateway, such as CatalogSearchMPGW.
  4. In the Multi-Protocol Gateway Policy dropdown, select default-accept-service-providers. This built-in policy is for working with WSRR.
  5. In the Type field, select dynamic-backends. It tells DataPower to get the back-end information dynamically for each request.
  6. In the Response Type and Request Type fields, select XML to indicate the data sent to and from the REST service. If these fields are set to Pass thru, then the WSRR subscription will not work.
  7. Create a Local Endpoint Handler. Click the + button in the Front Side Protocol section and then select HTTP Front Side Handler. This option enables you to invoke your service on DataPower using HTTP.
  8. In the new window, enter a name for the handler, such as CatalogSearchFSH, plus an unused port number. Remember the port number, which you will use later.
  9. For Allowed Methods and Versions, select GET method. This option means you can invoke the REST service to get data from the service, for example listing all available catalog entries. Using GET with a REST service is typical, so it is important that you enable GET requests. The Front Side Handler is shown below:
    Completed Front Side Handler for Multi-Protocol Gateway
    Completed Front Side Handler for Multi-Protocol Gateway
  10. Click Apply, which returns you to the previous window. The newly created HTTP Front Side Handler will be selected in the Front Side Protocol dropdown.
  11. Click Add to add the Front Side Handler to the gateway.

Next, you subscribe to the REST service registered in WSRR:

  1. Click the Subscriptions tab.
  2. Click Add WSRR Subscription.
  3. Enter a name for the subscription, such as the name of the REST service you are subscribing to, in the WSRR Subscription Name field, in this case CatalogSearch. Select New.
  4. Change the Synchronization method to Automatic (WSRR 7.5 or later). This option means that whenever the service is changed in WSRR, DataPower will automatically update itself when WSRR notifies it of the change.
  5. Leave the Subscription Object as Service Version.
  6. Enter the Object Name of the REST service, which for the Catalog Search service is Catalog Search. The REST service does not have a namespace, so leave the Namespace field empty.
  7. In the Use Object Version field, select On, because typically there are multiple versions of a service in WSRR. In the Object Version field enter 1.0.
  8. For the WSRR server, select the server from the drop-down menu that you created according to the instructions in Secure integration of WSRR with WebSphere DataPower. in "Secure integration of WebSphere Service Registry and Repository V8 with WebSphere DataPower V5". Here is the completed subscription:
    Completed WSRR subscription
    Completed WSRR subscription
  9. Click Attach.
  10. Set advanced properties: Click the Advanced tab.
  11. Under Process Messages Whose Body Is Empty, select On. This option enables GET requests with no body to be passed to the REST service. Such request are typical of REST get requests, where the resource to retrieve is specified entirely on the request URL.
  12. Click Apply.
  13. Click Save Config at the top to save the configuration to the domain. The CatalogSearchMPGW Multi-Protocol Gateway is now ready to serve requests for the Catalog Search REST service.

Testing the Multi-Protocol Gateway

You can download an Enterprise Application Archive (EAR) file at the bottom of this article. The application has an implementation of the Catalog Search service and a web client for that service. The web client lets you set the URL that the client calls, so that you can direct it to call the Catalog Search service through the Multi-Protocol Gateway that you created in DataPower.

Assuming that you have deployed CatalogServiceEAR.ear to WebSphere Application Server, as described in the Prerequisites section above, use browser to navigate to the test client at http://<host>:<port>/CatalogSearch/, where <host> and <port> are the correct host and port for the WebSphere Application Server instance where you deployed the EAR file. The client is self-explanatory and comes with default values for all parameters.

Change the value in the Endpoint field to point to the Multi-Protocol Gateway that you created earlier in DataPower. You create an HTTP URL using the host name of the DataPower appliance and the port of the Front Side Handler, and append CatalogSearch to the URL. For example, if the DataPower appliance host name is srvdp02, and the port number for the Front Side Handler is 20011, then the Endpoint value would be http://srvdp02:20011/CatalogSearch/.

Change the value of the Endpoint field to use the Multi-Protocol Gateway and leave the other fields with default values. Click Go to send a request to the Multi-Protocol Gateway. The results of the request are shown in the Results section. You should see that messages are sent successfully, through the Multi-Protocol Gateway on DataPower, using the endpoint information stored in WSRR. Here is an example invocation:

Invocation of REST service through DataPower Multi-Protocol Gateway
Invocation of REST service through DataPower Multi-Protocol Gateway

Conclusion

In this article, you registered a sample REST service in WSRR and created a Multi-Protocol Gateway in DataPower. You then subscribed DataPower to the REST service stored in WSRR, which caused DataPower to automatically route requests to the service registered in WSRR, using the endpoint URL registered in WSRR. Future parts of this article series will show you how to create policies in WSRR and attach them to the sample REST service so that they can be enforced by DataPower. These policies will demonstrate the new WS-MediationPolicy 1.7 features.

Acknowledgements

The authors would like to thank the following IBM colleagues:

  • Thomas Burke from WebSphere DataPower Development for his invaluable advice
  • Ian Heritage from IBM Worldwide WebSphere Technical Sales for his assistance and his helpful lab materials from the IBM Impact conference
  • Steven Willoughby from WSRR Development for his technical review of the article
  • Jason Yong from WSRR Development for his technical review of the article

Download

DescriptionNameSize
Sample REST service and WSRR data for this articledownload.zip27 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=954813
ArticleTitle=Using DataPower with WSRR and REST services, Part 1: Registering, exposing, and invoking a REST service with a sample client
publish-date=11202013