Transforming legacy assets into RESTful APIs using IBM API Management V2

Learn how to adapt and reuse software assets in a secure and controlled manner using IBM API Management. This article shows the process for transforming an existing WSDL-based SOAP web service and associated database table into a single RESTful service.

Share:

David T. Adcox (dtdcox@us.ibm.com), Advisory Software Engineer, IBM

Photo of David AdcoxDavid T. Adcox is an Advisory Software Engineer for IBM on the Websphere Virtual Enterprise development team in RTP, NC. In his 30-year professional software engineering career, he has worked on a wide variety of projects. Included in this experience is the development of multiple host access products, accounting products and the WebSphere Application Server.



Rick Gunderson (rgunderson@ca.ibm.com), IT Specialist, IBM

Rick Gunderson is an IT Specialist in Application Integration and Middleware in the IBM Software Group. In his 16 years at IBM, Rick has provided technical leadership on web-based projects for clients in a variety of industries, including Healthcare, Telecommunications, Agriculture and Energy.



Wei Liu, IBM Certified IT Specialist , IBM

Wei Liu is an IBM Certified IT Specialist and software developer in IBM Software Services for WebSphere (ISSW). Her expertise and interests include service integration, business process management, and design and development of Java EE and web services.



Naveen Yarlagadda (nyarlagadda@us.ibm.com), Software Engineer , IBM

Photo of Naveen YarlagaddaNaveen Yarlagadda has worked as a Software Engineer for IBM for the past 11 years. He is currently working as a consultant in the IBM software group. His experience includes working on the WebSphere stack, specializing in BPM and WebSphere performance.



16 April 2014

Introduction

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.

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

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
  2. After a successful login, create the API by clicking the Create link (Figure 3).
    Figure 3. Getting started page
    Getting started page

    Click to see larger image

    Figure 3. 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

    Click to see larger image

    Figure 4. 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
  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

    Click to see larger image

    Figure 6. 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

    Click to see larger image

    Figure 7. Location API overview page

    Location API overview page
  2. The auto-save feature in API Management

    Note that API Management does not have a save button. As new information is entered into the input controls, API management detects these changes and saves the information automatically.

    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

    Click to see larger image

    Figure 8. 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

    Click to see larger image

    Figure 9. 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

    Click to see larger image

    Figure 10. 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
  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

    Click to see larger image

    Figure 12. 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

    Click to see larger image

    Figure 13. 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

    Click to see larger image

    Figure 14. 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
  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

    Click to see larger image

    Figure 16. 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

    Click to see larger image

    Figure 17. DB2 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

    Click to see larger image

    Figure 18. 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

    Click to see larger image

    Figure 19. DB2 Query Configure definition

    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

Click to see larger image

Figure 20. 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

    Click to see larger image

    Figure 21. 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

    Click to see larger image

    Figure 22. 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

    Click to see larger image

    Figure 23. 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.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


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