Tutorial: Creating a REST API definition that invokes an existing SOAP service

About this tutorial

In API Manager, you will create a REST API that accesses a SOAP API to make data from the existing SOAP service available. This tutorial uses the same SOAP service as the Tutorial for creating a SOAP API tutorial, but exposes it in a different way.

Setting up a REST API definition

To set up a REST API, complete the following steps:

1. In API Manager, if you have not previously pinned the UI navigation pane then click the Navigate to icon . The API Manager UI navigation pane opens. To pin the UI Navigation pane, click the Pin menu icon .
2. Click Drafts in the UI navigation pane and then click the APIs tab. The APIs tab opens.
3. Click Add > New API.
4. Specify basic information about the API.
   1. In the Title field, enter Accounts.
   2. Leave the Name field as accounts when it is filled while you enter your title.
   3. Leave the Base Path field as /accounts.
   4. Leave the Version field as 1.0.0.
5. Expand Additional properties to specify additional properties for the API.
   1. From the API template field, select Default to indicate that you want to use the default template to create the API definition.
   2. Leave the remaining fields unchanged.
   
6. Add your API to a new Product and then create the API definition.
   1. Click Add a product.
   2. In the Title field, enter BankA Services.
   3. Leave the Name and Version fields unchanged.
   4. Ensure that the Publish this product to a catalog check box is selected and then select Sandbox as the target Catalog.
      
   5. Click Create API. The Design tab for the draft of your API definition opens.
7. In the Definitions section, click the Add Definition icon and then expand the new Definition by clicking it.
8. In the Name field rename the Definition to Account Output.
9. In the Properties subsection of the Definition is a single property called new-property-1. Rename the property to Balance, and in the TYPE column select double. Select the check box in the * column to mark the property as required.

   Marking a property as required is indicated to users in the OpenAPI (Swagger 2.0) definition of the API and can be enforced by a validate policy.

10. In the Paths section, click the Add Path icon , and then expand the new Path by clicking it.
11. In the Path field of your newly created Path, replace the contents with /balance.
12. In the Parameters subsection of the Path, expand the GET /balance operation by clicking it.
13. In the Parameters subsection for the GET /balance operation, click Add Parameter and then click Add new parameter.
14. Name your new parameter customer_id, and in the TYPE column select number-double. Select the check box in the REQUIRED column to mark the property as required.

    Marking a property as required is indicated to users in the OpenAPI (Swagger 2.0) definition of the API, is enforced by validate policies, and results in the test tool always generating the parameter as part of a sample API call.

15. In the Schema column of the 200 OK response in the Responses subsection, select your Account Output definition.
16. Click the Save icon to save your changes.

Adding and configuring your web service invocation

To add and configure the invoke and map policies that integrate your web service into your API definition, complete the following steps:

1. Download the SOAP WSDL file AccountService.txt. Rename this file AccountService.wsdl.
2. In the Services section, click the Add service icon . The Import web service from WSDL window opens.
3. Click Upload file.
4. Select the AccountService.wsdl file from your file system
5. Select the AccountService SOAP service and then click Done. In the Services section, the web service is listed.
6. Click the Assemble tab and then ensure that DataPower Gateway policies is selected.
7. Delete the existing invoke policy on the canvas by hovering your cursor over the policy and then clicking the Delete policy icon .
8. From the palette, drag the getBalance web service onto the dashed box that is displayed on the canvas. An invoke policy and two map policies are placed in the assembly. The first map policy assigns variables to the input of your web service invocation, while the second policy assigns outputs of your web service invocation to variables. The outputs of the first map and the inputs of the second map are generated from the WSDL that you uploaded.
9. Click the getBalance: input map policy and then click the Edit inputs icon in the Input column of the property sheet.
10. Click + input.
11. Configure the input according to the following table:

    Table 1. Web service input

    Property	Value
    Context variable	request.parameters.customer_id
    Name	customer_id
    Content type	none
    Definition	double

12. Click Done.
13. Click the circle corresponding to customer_id double on the input side and then click the circle corresponding to arg0 integer on the output side.
    
14. Close the property sheet.
15. Click the getBalance: output map policy in the palette and then click the Edit outputs icon in the Output column of the property sheet.
16. Click + output.
17. Configure the input according to the following table:

    Table 2. Web service output

    Property	Value
    Context variable	message.body
    Name	balance
    Content type	none
    Definition	#/definitions/Account Output

18. Click Done.
19. Click the circle corresponding to return integer on the input side and then click the circle corresponding to Balance number on the output side.
    
20. Click the Save icon to save your changes.

You have included the web service invocation in your assembly and mapped an input parameter to the appropriate part of the SOAP request and mapped the appropriate part of the SOAP response to a JSON output.

Testing your API definition

To test your API definition by using the API Manager test tool, complete the following steps:

1. Click the Test icon . The test tool opens.
2. If you have used the test tool before, click Change setup.
3. In the Catalog field, select your Sandbox Catalog.
4. In the Product field, select your BankA Services Product and then click Republish product to publish your Product so that it can be tested.
5. Click Next.
6. In the Operation field, select get /balance.
7. In the customer_id field, enter 12345.
8. Click Invoke. The response is displayed.
   Note: If you are using a self-signed certificate, you might be prompted to visit a provided URL. Click the link and then accept the certificate before returning to API Manager and clicking Invoke again.

What you did in this tutorial

In this tutorial, you completed the following activities:

• Set up a REST API definition
• Configured an API to invoke an existing web service and return its output
• Tested your API definition