Contents


Transforming legacy assets into RESTful APIs using IBM API Management V2

Comments

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 Related topics). This article builds on these concepts by demonstrating a transformational operation and linking operations to create a response.

Existing Artifacts

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
Data flow of the State Information use                     case
Data flow of the State Information use case

Control flow points of interest:

  1. 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.
  2. 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.
  3. The response of the SOAP service is used to execute a SQL query against the DB2 table where the state information is stored.
  4. The result of the DB2 query is used to generate a JSON response.
  5. 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.

  1. Log in to the API Manager console (Figure 2).
    Figure 2. API Manager login
    API Manager login
    API Manager login
  2. After a successful login, create the API by clicking the Create link (Figure 3).
    Figure 3. Getting started page
    Getting started page
    Getting started page
  3. 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
    APIs page
    APIs page
  4. Enter an API name, context and description and click Create (Figure 5).
    Figure 5. API Create Input panel
    API Create Input panel
    API Create Input panel
  5. 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
    Location API entry on APIs                             page
    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.

  1. 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
    Location API overview page
    Location API overview page
  2. 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:
    • 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
    Location API resources page
    Location API resources page
  3. 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
    New getStateInfo resource
    New getStateInfo resource
  4. 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
    Location API Overview tab
    Location API Overview tab
  5. 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.

  1. When the implementation tab is first displayed, by default, the Proxy method is selected (Figure 11). For this example, click the Assemble button.
    Figure 11. Implementation tab
    Implementation tab
    Implementation tab
  2. On the Assemble page (Figure 12), click the add operation button (1) and then select the Web Service Invoke Operation (2).
    Figure 12. Assemble page
    Assemble page
    Assemble page
  3. Next, define the Connect section of the operation. For the Connect section, you must:
    • 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
    Web Service Operation Connect                     definition
    Web Service Operation Connect definition
  4. 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
    Web Service Operation Discover                     definition
    Web Service Operation Discover definition
  5. 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 values:
    • 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
    Web Service Operation Configure                     definition
    Web Service Operation Configure definition
  6. 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.

  1. 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
    Add DB2 Execute Query
    Add DB2 Execute Query
  2. 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
    B2 Execute Query Connect                     definition
    B2 Execute Query Connect definition
  3. 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
    DB2 Execute Query Discover                     definition
    DB2 Execute Query Discover definition
  4. 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
    DB2 Query Configure defintion
    DB2 Query Configure defintion
  5. 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
Response definition
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.

  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
    API overview
    API overview
  2. 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 button (2) to execute the test.
    Figure 22. Test configuration
    Test configuration
    Test configuration
  3. 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
    Test result
    Test result

Conclusion

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.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Java development
ArticleID=968549
ArticleTitle=Transforming legacy assets into RESTful APIs using IBM API Management V2
publish-date=04162014