Build a simple assembly API using IBM WebSphere Cast Iron Live Web API Services

To reach new channels of mobile customers, organizations are investing in exposing existing IT assets via web APIs, making their business available instantly on mobile devices. IBM WebSphere® Cast Iron® Live Web API Services is a cloud offering that enables organizations to quickly expose enterprise APIs with an easy-to-use solution. Web and mobile developers can use these web APIs to build rich web and mobile applications. In addition, the Cast Iron Live API facilitates the building of developer portals for those exposed web APIs. This article shows how to build a simple assembly API for public availability using Cast Iron Live Web API Services.

Share:

Dinesh G Shetty (dinu.shetty@in.ibm.com), Senior IT Specialist, IBM

Author photoDinesh Shetty is a Senior IT Specialist at the IBM India Software Labs in Bangalore, working in the Software Services for WebSphere organization. He has over 12 years of experience in IBM middleware technologies like WebSphere MQ, Message Broker, and DataPower, and has implemented IT solutions in the areas of connectivity and integration. Dinesh also leads the IBM API Management Community for ISSW and drives consulting and enablement efforts in related areas. Previously, Dinesh worked in the WebSphere Message Broker development lab.



Vineet Gupta (vigupta6@in.ibm.com), Certified IT Specialist, IBM

author photo - vineet gupta 3Vineet Gupta is Certified IT Specialist skilled in IBM middleware products. He works in IBM Lab Services for WebSphere at India Software Labs, Gurgaon. He has 8 years of experience in developing solutions for multiple customers from various domain, including Distribution, Telecom, Healthcare, and Content management. He is also the author of a Support Pac on Enterprise exception patterns (MQ Support Pac ID08). He holds a Master of Computer Applications degree from Guru Jambheshwar University, Hisar.



05 April 2013

Introduction

Try it!

Sign up for a free, 90-day cloud-hosted trial of Cast Iron Live Web API Services.

You can use IBM WebSphere Cast Iron Live Web API Services in either of two ways. First, you can use the application programming interface (API) as a proxy that simply forwards the request to a user-defined back-end resource and relays the response received to the calling application. This method is most often used when the back-end resources are well defined and require no additional changes to the existing API. The Cast Iron Web API's capability to create and socialize documentation, as well as meter and monitor run time access to resources, are features that add value to existing APIs.

The second way you can use the API is as an assembly API that provides rich functionality for interacting with databases. In this case, it makes side calls to external services and transforms and aggregates the response before it's relayed to the calling application. Organizations can use this capability to build rich and functional APIs and also selectively define the interface from the available back-end interfaces.

In this article, we define a new interface for the Baggage API based on the existing one. We remove select elements from the existing Baggage API, defining only a subset of the elements from the original JKHLE Airways Baggage API. In addition, we exercise the uppercase transformation function for an element in the response.

Prerequisites

Cast Iron Web API instance

For this article, we built the examples using this instance: http://ciwebapi-qa.castiron.com/webapibuilder.

However, you are encouraged to use the production instance available at https://webapi.castiron.com/webapibuilder.

Alternatively, you can use http://ciwebapi-stg.castiron.com/webapibuilder to access and follow the exercises.

You should have a good understanding of integration concepts, and you should also be familiar with:

  • Fundamental concepts of JavaScript Object Notation (JSON) and XML
  • Fundamental concepts of Representational State Transfer (REST)
  • How to create a Cast Iron Web API administration login ID

To follow the instructions and examples in this article, you need:

  • A workstation with a standard Internet browser (Google Chrome is preferred)
  • A valid Cast Iron Web API administration ID and credentials
  • An Internet connection

Understanding the data flow

The use case in this solution is a simple assembly API that involves transformation of the response. The JKHLE Airways Baggage Services API is publicly available and provides a sample resource called baggage.json that returns a canned, sample response for a valid GET request (see Resources for a link). The Cast Iron Web API solution implements an assembly resource for the baggage.json resource in the JKHLE Airways baggage services. Figure 1 shows the flow of control in a sample transaction.

Figure 1. Data flow of the Baggage API use case
Image showing the data flow of the Baggage API use case

The control moves as follows:

Application IDs

For security purposes, application IDs are provided by Cast Iron Web API Services. Each invocation of the resource on the Cast Iron Web API requires an appended application ID to the URL. These IDs are generated when you publish the API from the Cast Iron Web API Publish utility. In this article, you will use the provided test client and so will not need to append the AppId parameter. You will need to use this parameter when you use an external test client.

  1. A sample mobile application invokes a GET request on the Cast Iron Web API (http://guptavineet.ciwebapi-qa.castiron.com/baggage/status&AppId=qsers). In this request, the application also appends the application ID.
  2. The status resource in the Cast Iron Web API consumes the request, validates the incoming application ID, and forwards the request to the baggage.json resource at the JKHLE Airways back end.
  3. The JKHLE back end responds with the precanned JSON response to the Cast Iron Web API.
  4. The Baggage API in the Cast Iron Web API performs the transformation on the response received from the back end.
  5. The Cast Iron Web API forwards the response to the calling application (in our case, the test interface provided in the product).

Now that you understand the concepts of proxy and assembly APIs and the relevance of application IDs, let's look at the steps required to build the solution.


Step 1. Create the Baggage API

To build the Baggage API, perform the following steps:

  1. Log in at https://ciwebapi-qa.castiron.com/webapibuilder/#tab=start using the administrative login that you would have received in an email after registration (see Figure 2).
    Figure 2. The Cast Iron Web API login page
    Image showing the Cast Iron Web API login page
  2. After successful login, create your API by clicking either the Create link on the "Getting Started with Web API" page or the APIs tab on the title bar (see Figure 3).
    Figure 3. The Getting Started with Web API page
    Image showing the Getting Started with Web API page
  3. On the "API definition page," populate the following fields as shown, then click Create to create your API definition (see Figure 4):
    1. In API name, type Baggage API.
    2. In context, type Baggage.
    3. In API description, type Status related to Passenger Baggage.
    Figure 4. Defining APIs
    Image showing how to define APIs

You have now successfully created your API, as shown in Figure 5. The next step is to create resources for it.

Figure 5. The successfully created API
Image showing the successfully created API

Step 2. Create the resource for the Baggage API

Creating the resource for the Baggage API consists of two tasks:

  1. Configure the resource definition
  2. Implement the transformation for the resource

Configuring the resource definition

To configure the resource definition, complete the following steps:

  1. Open the Baggage API in Edit mode by clicking either the Pencil icon or the Baggage API itself (see Figure 6).
    Figure 6. Editing the Baggage API
    Image showing how to edit the Baggage API
  2. On the Resource Definition tab, type Status in the Resource name field and To get status of Bags in the Description field.
  3. From the Method list, select the resource type—GET, POST, PUT, or DELETE—then click Add (see Figure 7).
    Figure 7. The Resource Definition tab for the Baggage API
    Image showing the Resource Definition tab for the Baggage API
  4. Configure the end point, expected response, and other parameters by clicking either the Pencil icon or the resource name (status, in this case). See Figure 8.
    Figure 8. Configuring the GET status resource
    Image showing how to configure the GET status resource
  5. On the next page, you define all the details related to resources, such as parameters, request headers, response headers, the request body, and the response body (see Figure 9).

    Note: Remember, the Response Body field is where you define the new and selective interface based on the existing back-end resource.

    Figure 9. Defining the resource
    Image showing how to define the resource

All the requests coming into this resource will be forwarded to the actual back-end resource at JKHLE Airways. On the Resource Details tab, you need to define only the response body. Figure 10 shows the method in which you define this resource as a mere proxy.

Figure 10. Implementing a proxy API
Image showing how to implement a proxy API

Also, take a moment to look at all the predefined headers provided in the Request Headers list, shown in Figure 11. You can also define all HTTP request or response headers here.

Figure 11. List of HTTP request and response headers from which to choose
Image showing the list of HTTP request and response headers

Saving changes in the Cast Iron Web API interface

There is no Save button. Cast Iron Web API Builder uses Web 2.0 technology to automatically update the server as you make changes. Make sure that you have performed the paste operation correctly: A red rectangle around the text field may appear if the JSON is not well formed.

Note: The request body or response body can be either JSON or XML.

For this article, use the JSON in Listing 1 as the response body. Remember, this is where you are defining a new and selective interface for the existing baggage interface. Copy the following code into the Response Body field.

Listing 1. JSON code for the Response Body field
{
	"Transformedstatus": {
		"bags": [
			{
				"id": "133944",
				"status": "On Belt",
				"checkInLocation": "LHR",
				"checkInTime": "Wed Jun 27 21:50:25 UTC 2012"
			},
			{
				"id": "133823",
				"status": "On Plane",
				"checkInLocation": "YYZ",
				"checkInTime": "Wed Jun 27 21:50:25 UTC 2012"
			}
		]
	}
}

You have now successfully defined the new interface in the Cast Iron Web API. Now, you must implement the resource to define an end point and HTTP method implementation.

Implementing the transformation for the resource

Click the Implement Resource tab to see parameters and other request details (if you defined them earlier). Figure 12 shows this tab.

Figure 12. The Implement Resource tab
Image showing the Implement Resource tab

Click the plus sign (+) to configure the end operation of the request coming to status. Select HTTP GET Operation from the list (see Figure 13). For this article, we use the HTTP GET operation to invoke the baggage.json resource available in JKHLE Airways Baggage API.

Figure 13. Defining the GET operation
Image showing how to define the GET operation

Now, complete the following steps:

  1. In the Connect section, define the properties as follows:
    • In the Name field, type jkhleairways.appspot.com.
    • In the Hostname field, type jkhleairways.appspot.com.
    • In the Port field, type 80.
    • In the URL field, type /baggage.json.

    You can also select an existing connection from the Existing Connections list, and then click Connect to save the resource and test the connection. See Figure 14.

    Figure 14. The end point configured for the HTTP GET operation
    Image showing the end point configured for the HTTP GET operation
  2. On the Define tab, define the response expected from the JKHLE Airways baggage.json resource.

    Notice that the response expected from the actual back end has currentLocation and destination in the response. These were removed in the new interface.

    Note: The Cast Iron Web API uses the sample data provided in the Request Body and Response Body text fields to infer the JSON or XML Schema. Based on this data, the Cast Iron Web API validates incoming requests (from a client) and responses (from the back end).

  3. Paste the JSON snippet from Listing 2 in the Response Body field.
    Listing 2. Sample code for the Response Body field
    {
    	"bagstatus": {
    		"bags": [
    			{
    				"id": "133944",
    				"status": "On Belt",
    				"checkInLocation": "LHR",
    				"checkInTime": "Wed Jun 27 21:50:25 UTC 2012",
    				"currentLocation": "JFK",
    				"destination": "LVS"
    			},
    			{
    				"id": "133823",
    				"status": "On Plane",
    				"checkInLocation": "YYZ",
    				"checkInTime": "Wed Jun 27 21:50:25 UTC 2012",
    				"currentLocation": "TRANSIT",
    				"destination": "LVS"
    			}
    		]
    	}
    }
  4. On the Configure tab, you transform the request fields (see Figure 15).

    You do this if you have query parameters on the request URL or if a POST request contains a payload.

    In our exercise, the GET request we're making does not have any parameters. So, you can ignore configuring transformation on the request.

    Figure 15. Configuring your request
    Image showing how to configure your request
  5. On the Review tab, review the inputs and outputs defined for the HTTP GET operation—in particular, the JKHLE baggage.json resource. See Figure 16.
    Figure 16. Review tab for the HTTP GET operation
    Image showing the Review tab for the HTTP GET operation
  6. When you click Response beneath the plus sign, you have two options for defining mapping between response messages from the end point to the expected response messages:
    • Under Response, click the SELECT VALUES, then click the top Select Available Value link. Choose a property, as shown in Figure 17.
      Figure 17. Defining mapping by using Select Available Value
      Image showing how to define mapping by using Select Available Value
    • Under Response, click MAP VALUES. This is a graphical way to define the mapping, as shown in Figure 18.
      Figure 18. Defining mapping by using Map Values
      Image showing how to define mapping by using Map Values
  7. Also, you can define transformation functions between source value and target value by clicking the plus sign, as shown in Figure 19.
    Figure 19. Using transformation functions
    Image showing how to use transformation functions

    In this article, we used the Uppercase function for the status attribute between the source message and the target message (see Figure 20).

    Figure 20. Using the Uppercase function to transform status
    Image showing how to use the Uppercase function to transform status

Step 3. Define the entitlement for the status resource

On the Entitlements tab, you can configure tiered entitlements for users. The Cast Iron Web API measures the number of invocations and provides alerts and warnings when a user exceeds the threshold value defined. For example, for basic and test purposes, you can define a value of 10 invocations per minute. You can also define multiple levels of entitlements.

Step up security by forcing the user to provide an application ID along with a secret key. The default level of access is Requires Id, as shown in Figure 21.

To define entitlements for the status resource, click the Entitlements tab, and then enter the following values:

  • In the Name field, type Basic.
  • In the Description field, type This is Basic entitlement.
  • In the Calls/Minute field, type 10.
  • From the Type of restriction list, choose Requires Id.
Figure 21. Defining entitlements
Image showing how to define entitlements

This entitlement allows only 10 calls per minute to the resource.


Step 4. Activate the resource

To activate the resource, on the Resource Definition tab, click the Activate icon against the resource. Note that if no entitlement is defined, the resource will not be activated (see Figure 22).

Figure 22. Resource activation
Image showing how to active your resource

Step 5: Test the resource

The Cast Iron Web API provides you with a test client. This client is the best method for testing your resource for functionality purposes. To run such a test, complete the following steps:

  1. Click the Test tab to display the test page shown in Figure 23.
    Figure 23. Test page for a resource
    Image showing the test page for a resource
  2. From the Select an API/Resource list, choose GET status.
  3. From the Select an Application list, choose Test application.
  4. Click Test to test the resource.

    A response with code 200 appears if the test is successful. The status in the transformed response should be in uppercase (see Figure 24).

    Figure 24. A successful response for the tested resource
    Image showing a successful response for the tested resource

Conclusion

You have successfully created an API in IBM WebSphere Cast Iron Live Web API services. You can view the same exercise as a demo on YouTube at http://www.youtube.com/watch?v=qQ_4VsmXiuI. Good luck! We look forward to your feedback.

Resources

Learn

Get products and technologies

Discuss

  • In the Cast Iron community forums, get answers to your technical questions and share your expertise with other WebSphere Cast Iron users.

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 Mobile development on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Mobile development, Cloud computing, WebSphere
ArticleID=863859
ArticleTitle=Build a simple assembly API using IBM WebSphere Cast Iron Live Web API Services
publish-date=04052013