Using JSON in WebSphere Cast Iron, Part 3: Designing JSON-based REST APIs

IBM® WebSphere® Cast Iron introduced two activities, Read JSON and Write JSON to work with JSON data. Part 1 of this 3-part series showed how to configure JSON handling activities to invoke JSON-based REST APIs and to create your own JSON-based REST APIs. Part 2 showed how to build an orchestration that invokes JSON-based REST APIs exposed by Salesforce.com to create an account. Part 3 shows how to design an orchestration that is exposed as a JSON-based API.

Share:

Rajath Ramesh (rajathr1@in.ibm.com), Software Engineer, IBM

Photo of Rajath RameshRajath Ramesh is a Software Engineer at the IBM India Software Labs. He started his career with IBM in 2010 as a developer in WebSphere Adapters and incubation projects. He is currently part of the WebSphere Cast Iron development team, specializing in Cast Iron Connectors, Cast Iron Studio, and the Connector Development Kit. He is a co-author of IBM Redbook: Getting Started with IBM WebSphere Cast Iron Cloud Integration.



Manjunatha D (manjunad@in.ibm.com), Software Engineer, IBM

Photo of Manjunatha DManjunatha D is a Software Engineer at the IBM India Software Labs. He works with the IBM WebSphere Adapters, IBM WebSphere Cast Iron, and IBM API Management teams.



31 July 2013

Also available in Chinese

Introduction

WebSphere Cast Iron (hereafter called Cast Iron) is widely used in data integration and migration across on-premise and off-premise applications. In the past, JSON was popularly used as the transport type for REST APIs because its format is lightweight compared to XML.

In Cast Iron, you can create and expose a JSON-based API, which is an orchestration that accepts request and sends a response in the JSON format. Cast Iron works with XML and XML schemas. Cast Iron introduced two new activities to work with JSON data, Read JSON and Write JSON. These activities are useful during the creation of an orchestration, which represents JSON-based API in Cast Iron. This article describes how to create an orchestration that can be exposed as an API that accepts and emits JSON data.


Building a JSON-based API to add two numbers in Cast Iron

In this scenario, you will learn how to expose a REST API, which accepts a JSON request having two numbers and sends the sum of the input numbers in a JSON message as the response by using the Read and Write JSON activities. The sample request and response JSON messages are shown in Table 1.

Table 1. Add two numbers for API sample request and response JSON messages
Request JSONResponse JSON
{
"number1":100"number2":120
}
{
"result":220
}

You must build the orchestration to accomplish the scenario illustrated above. This orchestration acts as a JSON-based REST API to add two numbers to the external world, as shown in Figure 1.

Figure 1. Add two numbers - API orchestration design
Add two numbers - API orchestration design

Click to see larger image

Figure 1. Add two numbers - API orchestration design

Add two numbers - API orchestration design
  1. The Receive Input Numbers (Receive request) receives the JSON request containing two numbers that need to be added. Table 2 shows the steps to complete Receive Input Numbers activity's checklist
Table 2. Receive Input Numbers activity
Checklist itemDescription
Pick Endpoint Select the HTTP endpoint.
Configure Give the input add to the URL (path after host name) and select POST for the HTTP method.
Map Output Create a new variable (body) based on the output parameters of the activity. This variable will be used to configure other activities of the orchestration.
  1. The Convert to XML activity (Read JSON) converts the JSON format data to XML:
    1. Configure Read JSON by completing the steps below. You must use the JSON message to configure JSON activities. Select the the Use JSON or XML Message option as the message type from the Configure window, as shown in Figure 2.
      Figure 2. Configure Convert to XML Activity
      Configure Convert to XML Activity

      Copy the request JSON message, as shown in Table 1, to the text area and click Generate Output Map. The Read JSON output parameters are generated, which you can see in the Map Outputs window, as shown in Figure 3. In Figure 3, for the given request JSON message, the respective XML schema has been generated and populated as Map Outputs. This enables easy mapping and processing of data that will be added.

      Figure 3. Convert to XML Activity Map Inputs
      Convert to XML Activity Map Inputs
    2. Select Map Inputs from the Checklist pane. Click the Select Inputs button and then select body as the input variable, as shown in Figure 4. Click Ok.
      Figure 4. Convert to XML Map Inputs - select inputs
      4. Convert to XML Map Inputs - select inputs

      After selecting the input variable, map the input variable to jsonText as shown in Figure 5.

      Figure 5. Convert to XML Map inputs - mapping
      Convert to XML Map inputs - mapping
    3. Select Map Outputs from the Checklist. Click Copy and then select the map output parameters to create a new variable based on the output parameters of the activity. Rename the created variable to Numbers, as shown in Figure 6. Numbers is highlighted in blue in the top right pane in Figure 7.
      Figure 6. Convert to XML Map Outputs – create output variable
      Convert to XML Map Outputs – create output variable

      Figure 7 shows the Map Outputs window after performing the required mapping.

      Figure 7. Convert to XML Map Outputs – mapping
      Convert to XML Map Outputs – mapping
  2. Use the map variable to add numbers and a map:
    1. Drag and drop the Map Variable activity to the work flow pane from Transforms. Click Select Inputs to select the variable Numbers, which was already created at Convert to XML Map Outputs (Read JSON). Now we have the value that will be added.
    2. Create the variable result of type "Decimal". You need this variable to hold the result of the Add function.
    3. Drag and drop the Add function. Map Number1 and Number2 to the Add function and then map the result of the Add function to the result variable (see Figure 8), which was created in Step b.
      Figure 8. Add two numbers
      Add two numbers
  3. Now add and configure the JSON Activity (Write JSON):
    1. Configure the Write JSON activity by completing the steps below. As we are using a JSON message to configure the JSON activities, select the Use JSON or XML Message option as the message type from the Configure window. Copy the JSON or XML message into the text area and click Generate Map, as shown in Figure 9. The Write JSON input parameters are generated, which you can see in the Map Input area, as shown in Figure 10.
      Figure 9. Configure Convert to JSON Activity
      Configure Convert to JSON Activity
    2. Click Map Inputs from the Checklist pane and then click the Select Inputs button to select the input variable result. Map result to the Result XML Variable, as shown in Figure 10.
      Figure 10. Convert to JSON Map Inputs
      Convert to JSON Map Inputs
    3. Click Map Outputs and copy the JSON text to create a new variable resultInJsonFormat, as shown in Figure 11. You can send the result back, or you can use "resultInJsonFormat" to configure the next activity.
      Figure 11. Convert to JSON Map Outputs
      Convert to JSON Map Outputs
  4. The Send Result Activity (HTTP Send Reply) sends the result summary in a JSON format. The checklist in Table 3 indicates that you should map the resultInJsonFormat to the body.
Table 3. Send Result Activity
ChecklistDescription
Map Input Select the input resultInJsonFormat and map it to the body of the Send Reply.

Testing the API

To test the API, complete the following steps:

  1. Click the Project tab, right-click the Orchestration name, and click Start Orchestration as shown in Figure 12.
    Figure 12. Start CustomAPI orchestration
    Start CustomAPI orchestration
  2. Click the Tools menu and select HTTP Post Utility to invoke the API. The HTTP Post window appears. Paste your request JSON message (that was shown in Table 1) to the text box Post a message. Enter the URL configured in the HTTP Receive Request Activity, and then select the method POST. Click the Submit button to post the request as shown in Figure 13.
    Figure 13. HTTP Post Utility
    HTTP Post Utility
  3. Wait for the server response. Once you get the response, you can see the output in the HTTP Post Utility response, as shown in Figure 13.

Conclusion

In Part 3 of this series, you learned how to use Read JSON and Write JSON activities to create custom JSON-based APIs, and eventually exposed them to the external world by deploying them on the Appliance or Cast Iron Live. By using the instructions in this article series, you have learned to configure Read JSON and Write JSON activities using an XML schema or a sample JSON message.

Acknowledgments

The authors would like to thank Raghavendra K. Neelekani for reviewing and providing valuable suggestions for this article series.

Resources

Learn

Discuss

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
ArticleID=939325
ArticleTitle=Using JSON in WebSphere Cast Iron, Part 3: Designing JSON-based REST APIs
publish-date=07312013