Using DataPower with WSRR and REST services, Part 1
Registering, exposing, and invoking a REST service with a sample client
This content is part # of # in the series: Using DataPower with WSRR and REST services, Part 1
This content is part of the series:Using DataPower with WSRR and REST services, Part 1
Stay tuned for additional content in this series.
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 (V188.8.131.52) 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.
- WSRR V184.108.40.206 (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
<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
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:
- Ensure that you are logged into the WSRR Web UI.
- Change to the Administrator perspective using the Perspective dropdown menu at the top of the page.
- Under the Actions dropdown menu, select Import.
- 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:
- Ensure that you are logged into the WSRR Business Space UI and on the Operation space.
- 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.
- In the Collection widget, click http://CSProductionHost:9443/services/catalog/ (1.0) to open it in the Detail widget.
- Click the Pencil icon at the top right of the widget to edit the endpoint.
- 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
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 :
- Click the Pencil icon next to the Visibility section.
- In the Visibility dialog, uncheck External and check Internal.
- Click Close. Here is the completed endpoint:
Completed endpoint for REST service
- 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:
- Ensure that you are logged into the WSRR Business Space UI and on the Operation space.
- 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.
- In the Collection widget, click http://CSStagingHost:9081/services/catalog (1.0) to open the staging endpoint in the Detail widget.
- 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.
- Navigate to the DataPower Control Panel for your domain, and click the Multi-Protocol Gateway icon.
- On the Configure Multi-Protocol Gateway page, click Add.
- In the Multi-Protocol Gateway Name field, enter a name for your new gateway, such as
- In the Multi-Protocol Gateway Policy dropdown, select default-accept-service-providers. This built-in policy is for working with WSRR.
- In the Type field, select dynamic-backends. It tells DataPower to get the back-end information dynamically for each request.
- 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.
- 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.
- 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.
- 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
- 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.
- Click Add to add the Front Side Handler to the gateway.
Next, you subscribe to the REST service registered in WSRR:
- Click the Subscriptions tab.
- Click Add WSRR Subscription.
- 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.
- 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.
- Leave the Subscription Object as
- 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.
- 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
- 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
- Click Attach.
- Set advanced properties: Click the Advanced tab.
- 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.
- Click Apply.
- 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
<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
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
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.
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
- WebSphere Service Registry and Repository (WSRR) resources
- WSRR information center
A single Web portal to all WSRR documentation, with conceptual, task, and reference information to help you install, configure, and use the product.
- WSRR product page
Product descriptions, product news, training information, support information, and more.
- WSRR requirements
Hardware and software requirements.
- WSRR forum
developerWorks forum where you can get answers to your technical questions and share your expertise with other WSRR users.
- WSRR Information Portal
This wiki provides an alternative portal for quick access to a wide variety of WSRR resources, and also makes it easy for you to give feedback on the product.
- YouTube: WSRR demos
Free video tutorials on a variety of WSRR tasks.
- Service Registry Sagacity blog
Topics and techniques for WSRR, plus user comments and questions.
- WSRR handbook
This IBM Redbooks publication discusses the architecture and functions of WSRR, along with sample integration scenarios that you can use to implement the product in an SOA.
- Service Lifecycle Governance with WSRR
This IBM Redbooks® publication uses business scenarios to illustrate SOA governance using WSRR as the authoritative registry and repository.
- Secure integration of WSRR with WebSphere DataPower
This developerWorks article shows you how to integrate DataPower with a secured WSRR server.
- Using WSRR V8 and DataPower V5 for service level mediation policy enforcement
This developerWorks article shows you how to create a web service proxy in DataPower for a web service registered and governed in WSRR. The article also shows you how to attach a service-level mediation policy to the service in WSRR and then enforce it in DataPower.
- Updates to configuration profile required for using WS-MediationPolicy 1.7
This topic in the WSRR information center shows you how to update your WSRR profile to use the WS-MediationPolicy 1.7 support.
- Governing an existing REST service
This tutorial in the WSRR information center shows you how to register a REST service in WSRR.
- Creating and editing actions
This topic in the WSRR information center shows you how to add an action to create a WS-MediationPolicy 1.7 policy.
- WSRR information center
- WebSphere DataPower resources
- WebSphere DataPower information center
A single Web portal to all WebSphere DataPower documentation, with conceptual, task, and reference information on installing, configuring, and using the various WebSphere Appliances.
- WebSphere DataPower product page
Product descriptions, product news, training information, support information, and more for all DataPower Appliances.
- WebSphere DataPower product library
Product announcements, case studies, white papers, and more.
- WebSphere DataPower forum
Get answers to your technical questions and share your expertise with other WebSphere DataPower users.
- Communicating between stylesheets using WebSphere DataPower context variables
This developerWorks article shows you how to set and read DataPower variables in a stylesheet.
- WebSphere DataPower Appliance Handbook
The expert Guide to Deploying, Using, and Managing DataPower Appliances, from IBM Press.
- IBM WebSphere DataPower SOA Appliances Part I: Overview and Getting Started
This DataPower Redpaper describes DataPower stylesheets and other topics.
- WebSphere DataPower information center
- WebSphere resources
- developerWorks resources