Software asset reuse has been an often sought-after yet infrequently achieved goal for IT departments. Adaptation of older assets in an ever-changing ecosystem makes reuse a time-consuming task. Frequently, too, a lack of knowledge of what assets are available prevents reuse and leads to reengineering. In either case the end result, too often, is redevelopment of a solution that already exists in another form.
The IBM API Management Version 2.0 product provides a platform from which an organization may expose web APIs in a secure and controlled manner. One feature of note in the product is the ability to transform existing APIs into modern web APIs. This article demonstrates how to use API Management to transform an existing WSDL-based SOAP service and associated database table into a web service.
The basic details on how to construct a simple assembly API using API Management are covered in the article Build a simple assembly API using IBM WebSphere Cast Iron Live Web API Services (see Resources). This article builds on these concepts by demonstrating a transformational operation and linking operations to create a response.
In this sample use case, there are two legacy artifacts that will be repurposed into a single web service. The first artifact is a SOAP-based web service that returns a United States state code using the provided latitude and longitude value. The second artifact is a DB2 database table of United States state facts. In this example, the SOAP web service response will be linked to a DB2 table lookup to provide a JSON-formatted response for a single web service.
Figure 1. Data flow of the State Information use case
Control flow points of interest:
- Any Web or Mobile client can invoke an HTTP Get request on the IBM API Management service for this solution. The request must provide a single String value that contains the latitude and longitude information as well as the Application ID of the calling application.
- The locationService resource of the Location API consumes the request. The application ID provided is validated and then the latitude/longitude parameter is passed to the legacy SOAP service.
- The response of the SOAP service is used to execute a SQL query against the DB2 table where the state information is stored.
- The result of the DB2 query is used to generate a JSON response.
- The JSON response is returned to caller from step #1.
The implementation shown above may be accomplished in six steps. The remainder of this document will describe the actions needed to complete this example.
Step 1. Create Location API
In this step, a new Location API is constructed. This API will hold the new API resource being created to support the state information web service.
- Log in to the API Manager console (Figure 2).
Figure 2. API Manager login
- After a successful login, create the API by clicking the Create link
Figure 3. Getting started page
- Clicking the Create link displays the APIs page. On this page,
click the add REST API button to create a new API (Figure 4).
Figure 4. APIs page
- Enter an API name, context and description and click Create
Figure 5. API Create Input panel
- After clicking the Create button, the new API is
created and a new entry is shown in the list of APIs on the
APIs page (Figure 6).
Figure 6. Location API entry on APIs page
Step 2. Create getStateInfo resource
Once the new Location API has been constructed, a new resource is needed. Each API created may contain multiple web services. Each service endpoint is described as an API Resource. These API resources are managed on the API’s Resources tab.
- Click the Location API hot link or edit icon to enter the Location API overview page (Figure 7). From this page
the Location API can be edited.
Figure 7. Location API overview page
- Specify a unique context for the new resource. Include any parameters needed for this resource in the context specification. In this example, the ‘latlng’ parameter is specified (item 1 on Figure 8).
- Create a resource description (item 2 on Figure 8).
Once the context and description entries are complete, click the Add button.
Figure 8. Location API resources page
Click the Resources tab and then click the Add a Resource button. This
creates a new resource for the API. By default the resource is
designated as a GET operation. You must:
- After the new resource is created, it is shown in the Location API’s
resources list (Figure 9). The new resource can be edited by clicking
the resource hot link or the edit icon.
Figure 9. New getStateInfo resource
- In the getStateInfo resource Overview tab (Figure 10), edit the
description field (1) and the Response Body (2). Enter an appropriate description
for parameter latlng. The Response Body for this resource is specified
using the JSON format.
Figure 10. Location API Overview tab
- Now click the Implementation tab and begin the next step, defining the web service invocation.
Step 3. Create Web Service Invoke operation
In this step you define the first of two operations. Operations contain the information needed to access the legacy resource to be represented by the new web service. One or more operations can be defined for the new resource. The two operations needed for this service are:
- Web Service Invoke Operation
- DB2 Execute Query Operation (covered in Step 4)
First define the Web Service Invocation resource, which returns a state code for the given latitude and longitude.
- When the implementation tab is first displayed, by default, the Proxy
method is selected (Figure 11). For this example, click the Assemble
Figure 11. Implementation tab
- On the Assemble page (Figure 12), click the add operation
and then select the Web Service Invoke Operation (2).
Figure 12. Assemble page
- Next, define the Connect section of the operation. For the Connect section,
- Specify the existing service connection. In this example, there is a web-based WSDL file that is identified in the URL for the WSDL field.
- Specify a name.
Once these two fields are defined, click the Test button to validate the WSDL.
Figure 13. Web Service Operation Connect definition
- Once the WSDL is validated, a list of available fields is presented in the
Discover section of the operation. In this section, the list of available
objects is displayed in a tree on the left. On the right is a list of
available fields for the selected object on the left. In this example, the
Service being invoked is called LocationDataImplService. The port type is
called LocationDataImpl. The operation is getStateName. When the operation
is selected, a list of available fields is displayed. The field needed for
identifying the latitude and longitude is called latlng. After
selecting latlng, a mapping is needed between the input parameters of this
newly defined service and the legacy service being defined. This mapping
is done in the Configure section of the operation. Proceed to that
section by clicking Configure on the progress bar.
Figure 14. Web Service Operation Discover definition
- From the Configure section the inputs from the new API can be mapped to the
inputs of the legacy service. Two methods are available for mapping these
- The Select Values method provides a list of possible values to choose for each request input defined for the new service. The list of possible values was defined in this case based on what was selected in the previous step (Discover).
- The Map Values method is the one being used in this example. In this method a list of input values for the new service is shown on the left under the Available Values header. The list of input values for the legacy service is shown on the right under the Input Variables header (Figure 15). A line may be drawn from point (1) to point (2) to map the values. Additional transformation operations may be made to the value using the control (+). In this case, no such transformations are needed.
Once the mapping is complete, click the Review section of the progress bar.
Figure 15. Web Service Operation Configure definition
- The Review section provides a summary of the input mapping actions just taken. It also provides input controls which allow for special handling of error conditions. Review the mapping actions taken and add any special error conditions if desired. For this example, no special conditions need to be defined.
Step 4. Create DB2 Execution Query
Once the Web Service invocation is complete, the results of that call are used to perform a SQL query on a DB2 table. This step describes the actions needed to support such an operation.
- Similar to step 3, add a new operation. First click the Add Operation
button (1) and then select the DB2 Execute Query (2) as shown in Figure 16.
Figure 16. Add DB2 Execute Query
- Clicking the Execute Query action creates a new DB2 Execute Query
operation. The existing connection now needs to be defined. This is where the
DB2 database connectivity is specified (Figure 17). Once all the
details are entered, click the CONNECT button to validate the connection
and proceed to the Discover definition.
Figure 17. DB2 Execute Query Connect definition
- On the Discover section of this operation, the query used to extract the
data from the table needs to be defined. By default, API Management
prompts with the Build Query input page. In this example, the SQL statement
is already known, so click the Enter Query button (1). Then enter the SQL
statement into the input control (2) as shown Figure 18.
Figure 18. DB2 Execute Query Discover definition
- Click the Configure section of the progress bar to proceed. On this
page, the result of the Web Service Invocation is mapped as input to the
DB2 Execute Query SQL statement. API Management defaults to the
Select Values style input. Click the Map Values button (1). Then draw a line
from the result value of the Web Service Invoke Operation (2)
on the left (under
Available values) to the SQL Input Variables on the right (3) as shown in Figure 19.
Figure 19. DB2 Query Configure definition
- As with the Web Service Invocation, the Review section provides a summary of the input mapping actions described in the Configure section. It, too, provides input controls which allow for special handling of error conditions. Review the mapping actions taken and add any special error conditions if desired. For this example, no special conditions need to be defined.
Step 5. Define Response
Now that both legacy operations have been defined, the new web service needs a response. The response will use the results from the DB2 Query and provide them as JSON data as described in the Step 2 definition of the Response Body.
First, click the Response button (1) as shown in Figure 20. By default, API Management presents the Select Values style input. Click the Map Values button (2) to select that style input. On the Map Values input page, draw a line from left to right for all value mappings. All possible values from the previously defined operations are listed on the left under the Available values heading. All result values are listed on the right under the Input variables heading. Draw a line from the left to the right for each value in the JSON result (3).
Figure 20. Response definition
As with the Web Service Invocation, the Review section provides a summary of the input mapping actions described in the Configure section. It also provides input controls which allow for special handling of error conditions. Review the mapping actions taken and add any special error conditions if desired. For this example, no special conditions need to be defined.
Step 6. Test the new service
With the Response defined, the new service is ready for testing. API Management provides a test framework for APIs it contains. The test tool is available from the API input page defined in Step 1.
- Go back to the API overview page as shown in Figure 21. On this page, start the service by
clicking the start button (1). When the service starts, click the
Test tab (2) to launch the test tool.
Figure 21. API overview
- On the test tool page shown in Figure 22, select the API resource, select the test
application, and specify any input values first (1), then click the Test
to execute the test.
Figure 22. Test configuration
- Click the Test button to exercise the new API. The result of the call is
displayed below the input values. Figure 23 shows the result of the getStateInfo
resource defined in this article.
Figure 23. Test result
As demonstrated in this article, API Management provides a rich toolset that will aid you in publishing and managing software assets. Like a fresh coat of paint, repackaging and publishing older APIs makes them attractive to potential users. API Management capabilities extend beyond the API authoring tools discussed here. The product also contains API metering functionality, analytics, and a user-configurable API portal.
- Build a simple assembly API using IBM WebSphere Cast Iron Live Web API Services (developerWorks, April 2013) explains the basics of constructing a simple assembly API using IBM API Management.
- API Management 2.0 Redbook This Redbooks publication was used during the creation of this article. It provides a good overview of the tool and details on how to perform many of the fundamental tasks.