Contents
The Web Services Repository stores information about Web Services whose definitions have been imported using Policy Studio or API Service Manager. The WSDL files that contain these Web Services definitions are stored together with their related XML Schemas. Clients of the Web Service can then query the repository for the WSDL file, which they can use to build and send messages to the Web Service using the API Gateway.
When you import WSDL files into the repository, this auto-generates a Service Handler that is used to control and validate requests to the Web Service and responses from the Web Service. You can import the WSDL file from the file system, a URL, or from a UDDI registry. You can also test the WSDL file for compliance with Web Services Interoperability (WS-I) standards. This topic describes how to test for WS-I compliance, how to import a Web Service definition into the repository, and shows what is created at each step.
Before importing the WSDL file, you can check it for compliance with the WS-I Basic
Profile. The Basic Profile consists of a set of assertions and guidelines on how
to ensure maximum interoperability between different implementations of Web Services.
For example, there are recommendations on what style of SOAP to use
(document/literal
), how schema information is included in WSDL files,
and how message parts are defined to avoid ambiguity for consumers of WSDL files.
The Policy Studio uses the Java version of the WS-Interoperability Testing Tools to test imported WSDL files for compliance with the recommendations in the Basic Profile. A report is generated showing which recommendations have passed and which have failed. While you can still import a WSDL file that does not comply with the Basic Profile, there is no certainty that consumers of the Web Service can use it without encountering problems.
Important | |
---|---|
Before you run the WS-I compliance test, you must ensure that the Java version of the Interoperability Testing Tools is installed on the machine on which the Policy Studio is running. You can download these tools from www.ws-i.org. |
To configure the location of the WS-I testing tools, select Window ->
Preferences from the Policy Studio main menu. In the Preferences
dialog, select the WS-I Settings, and browse to the location of the WS-I
testing tools. You must specify the full path to these tools (for
example, C:\Program Files\WSI_Test_Java_Final_1.1\wsi-test-tools
).
For more details on configuring WS-I settings, see the Policy Studio Preferences
topic.
Running the WS-I Compliance Test
To run the WS-I compliance test on a WSDL file, perform the following steps:
-
Select Tools -> Run WS-I Compliance Test from the Policy Studio main menu.
-
In the Run WS-I Compliance Test dialog, browse to the WSDL File or specify the WSDL URL.
-
Click OK. The WS-I Analysis tools run in the background in Policy Studio.
The results of the compliance test are displayed in your browser in a WS-I Profile Conformance Report. The overall result of the compliance test is displayed in the Summary. The results of the WS-I compliance tests are grouped by type in the Artifact: description section. For example, you can access details for a specific port type, operation, or message by clicking the link in the Entry List table. Each Entry displays the results for the relevant WS-I Test Assertions.
The Web Services Repository is displayed under the Business Services node in the Policy Studio tree. WSDL files are imported into Web Service Groups, which provide a convenient way of keeping groups of related Web Service definitions together. You can import a WSDL file into the default group by right-clicking the Web Services node, and selecting Register Web Service.
Alternatively, you can add a new Web Services group by right-clicking the default Web Services group, or the Web Services Repository node, and selecting Add a new Web Services group. When the new group is added, you can right-click it in the tree, and select Register Web Service.
In the Import WSDL wizard, the Load WSDL screen enables you to choose the WSDL location from the following options:
-
File system
-
URL
-
UDDI registry
Select the appropriate option depending on the location of the WSDL that you wish to import. If you wish to retrieve a WSDL file from a UDDI directory, see the Retrieving WSDL Files from a UDDI Registry topic.
Click Next.
The WSDL Operations screen of the wizard displays all operations defined in the WSDL file. The Relative Path, Binding, and Namespace of each operation are also displayed. Select the operations that you wish to create policy resolvers for. The Policy Studio uses the Web Service location, SOAP operation, and SOAP Action specified in the WSDL to create Relative Path, SOAP Operation, and SOAP Action policy resolving filters in the Service Handler.
Use the Remove unselected operations from the WSDL checkbox to specify whether the Policy Studio removes unselected operations from the WSDL file stored in the repository. As a result, removed operations are not exposed to clients that download the WSDL file for the Web Service.
Important | |
---|---|
When a request is made to the API Gateway for WSDL that has been imported into the
Web Services Repository, it changes the address of the Web Service
specified in the |
Click Next.
Configure the following options on this screen:
Secure this virtualized service with a WS-Policy
Specifies whether to use a WS-Policy to secure the Web Service being virtualized by the API Gateway. When this setting is selected, the Secure Virtual Service dialog is displayed after the Import WSDL wizard. This dialog enables you to configure a WS-Policy that the API Gateway enforces on messages that it receives from the client. This setting is unselected by default.
Use the WS-Policy in the WSDL to connect securely to the back-end Web Service
When the WSDL file includes WS-Policy information, this setting specifies whether to use this WS-Policy to connect securely to the Web Service. This setting is enabled (and selected by default) only if the selected WSDL file includes WS-Policy information.
Click Next.
The final screen in the wizard enables you to select where to deploy the newly created policy (or policies). The Deploy Policy screen displays a list of all available Services and their corresponding Relative Paths. Select a Relative Path under which the policy is deployed. All requests arriving on the selected path are dispatched to the newly created policy.
Click Finish.
When you click Finish in the wizard, the Secure Virtual Service dialog is displayed. This enables you to specify policies to enforce security between a client and the API Gateway. For more details, see Securing a Virtual Service Using Policies.
In addition, if the imported WSDL file contains WS-Policy assertions, you are prompted to configure settings to enforce security between the API Gateway and the Web Service. For more details, see Configuring Security Policies from WSDL Files.
When you have finished configuring security policies, the Summary dialog displays details on the imported WSDL file. For example, this includes the location of the WSDL file, and a tab for each Web Service virtualized by the API Gateway. Each tab includes the path to the Web Service that is published by the API Gateway.
WSDL Import Summary Options
The Summary dialog also enables you to configure the following options on the tab for each Web Service:
Validation | If you wish to use a dedicated validation policy for all messages sent to the Web Service, select this checkbox, and click the browse button to configure a policy in the dialog. For example, this enables you to delegate to a custom validation policy used by multiple Web Services. |
Routing | If you wish to use a dedicated routing policy to send all messages on to the Web Service, select this checkbox, and click the browse button to configure a policy in the dialog. For example, this enables you to delegate to a custom routing policy used by multiple Web Services. |
WSDL Access Options | Select whether to make the WSDL for this Web Service available to clients. Allow the API Gateway to publish WSDL to clients is selected by default. The published WSDL represents a virtualized view of the Web Service. Clients can retrieve the WSDL from the API Gateway, generate SOAP requests, and send them to the API Gateway, which routes them on to the Web Service. For more details, see the section called “Publishing the WSDL”. |
These options enable you to configure the underlying auto-generated Service Handler (Web Service Filter) without having to navigate to it in the Policies tree. These are the most commonly modified Web Service Filter options after importing a WSDL file. Changes made in the Summary dialog are visible in the underlying Web Service Filter. For more details, see the Web Service Filter topic.
You can also access these options under the Listeners node after the WSDL file has been imported. Right-click the appropriate Web Service Resolver node, and select Quick-Edit Policy to display a dialog that enables you to configure these options.
What is created when you import the WSDL file depends on whether you configured a policy to enforce security between the client and the API Gateway, and whether the WSDL file contains any WS-Policy annotations. However, assuming that the default options are selected in the WSDL Import wizard, the following list summarizes what is created by the wizard:
Web Service
A new Web Service tree node is created for each imported WSDL file in the Policies tree. This tree node contains the WSDL file, together with any imported resources, such as other WSDL files or schema files. Click the new Web Service node to view the list of imported WSDL files and XML Schemas. The Schemas are listed by namespace. You can view the imported WSDL file by clicking the location of the WSDL file under the Web Service node. If you have selected to remove unselected operations from the WSDL, these operations are removed from the stored WSDL.
Web Service Resolver
A new Web Service Resolver node is created for each imported Web Service in the Services tree view. The Web Service Resolver is used to identify messages destined for this Web Service, and to map them to the Service Handler (Web Service Filter) for the Web Service.
Service Handler
A Service Handler for the Web Service is created under the generated policy in the Policies tree. This is used to control and validate requests to the Web Service and responses from the Web Service. The Service Handler is named after the Web Service (for example, Service Handler for 'HelloWorldService'). The Service Handler is a Web Service Filter, and is used to control the following:
-
Routing
-
Validation
-
Message request/response processing
-
WSDL options
-
Monitoring options
For more details, see the Web Service Filter topic.
Policy Container
A container for the newly generated policies is created under the Generated Policies node in the Policies tree. The new container is named after the service (for example, Web Services.HelloWorldService).
Policy
A policy for the Web Service is created in the generated policy container.
The policy name includes the relative path to the service (for example,
/HelloWorldService/HelloWorld). Clients can specify
WSDL
on a request query string to retrieve the WSDL file (for example,
http://localhost:8080/HelloWorldService/HelloWorld?WSDL
).
For more details, see the section called “Publishing the WSDL”.
Security Policies
If you decided to configure a WS-policy to enforce security between the client and the API Gateway (as described earlier in the section called “Secure Virtual Service”), or if the imported WSDL file contains WS-Policy assertions, a number of additional policies are automatically created in the generated policy container. These generated policies include the filters required to generate and/or validate the relevant security tokens (for example, SAML tokens, WS-Security Username tokens, and WS-Addressing headers). These policies perform the necessary cryptographic operations (for example, signing/verifying and encryption/decryption) to meet the security requirements of the specified policies.
When the WSDL has been imported into the Web Services Repository, it can be retrieved by clients. In effect, by importing the WSDL into the repository, you are publishing the WSDL. In this way, consumers of the services defined in the WSDL can learn how to communicate with those services by retrieving the WSDL for those services. However, to do this, the location of the service must be changed to reflect the fact that the API Gateway now sits between the client and the defined service.
For example, assume that the WSDL file states that a particular service
resides at http://www.example.com/services/myService
:
<service name="myService"> <port binding="SoapBinding" name="mySample"> <wsdl:address location="http://www.example.com/services/myService"/> </port> </service>
When deployed behind the API Gateway, this URL is no longer accessible to consumers of the service. Because of this, clients must send SOAP messages through the API Gateway to access the service. In other words, they must now address the machine hosting the API Gateway instead of that directly hosting the service.
When the WSDL file has been published to the repository, clients can retrieve it.
However, when returning the WSDL to the client, the API Gateway dynamically changes
the value of the location
attribute in the service
element
in the WSDL file to point to the machine on which the API Gateway resides. The details
regarding the physical location of the Web Service are preserved in the
Connection filters, responsible for routing messages on to
the service.
Assuming that the API Gateway is running on port 8080
on a machine called
SERVICES
, the location specified in the exported WSDL file is changed
to the following:
<service name="myService"> <port binding="SoapBinding" name="mySample"> <wsdl:address location="http://SERVICES:8080/services/myService"/> </port> </service>
When the modified WSDL file is distributed to the client, it now routes messages to the machine hosting the API Gateway instead of attempting to directly access the Web Service.
Accessing the WSDL
For the client to access this modified WSDL file, the Policy Studio provides a WSDL retrieval
facility whereby clients can query the Web Services Repository for the
WSDL file for a particular Web Service. To do this, the client must pass the name
WSDL
on the query string to the Relative Path mapped to the
policy for this Web Service.
For example, if the policy is deployed under
http://SERVICES:8080/services/getQuote
,
the client can retrieve the WSDL for this Web Service by sending a
request to http://SERVICES:8080/services/getQuote?WSDL
.
When the client has a copy of the updated WSDL file, it knows how to create correctly
formatted messages for the service, and more importantly, it knows to route messages
to the API Gateway rather than to the Web Service directly.
Publishing to UDDI
For details on how to publish a WSDL file registered in the Web Services Repository to a UDDI directory, see the Publishing WSDL Files to a UDDI Registry topic.