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 JSON||Response JSON|
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
- 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
|Pick Endpoint||Select the HTTP endpoint.|
|Configure|| Give the
|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.|
- The Convert to XML activity (Read JSON) converts the JSON format data
- 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
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
- 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
After selecting the input variable, map the input variable to jsonText as shown in Figure 5.
Figure 5. Convert to XML Map inputs - mapping
- 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.
Numbersis highlighted in blue in the top right pane in Figure 7.
Figure 6. 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
- 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.
- Use the map variable to add numbers and a map:
- 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.
- Create the variable result of type "Decimal". You need this variable to hold the result of the Add function.
- 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
- Now add and configure the JSON Activity (Write JSON):
- 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
- 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
- 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
Figure 11. Convert to JSON Map Outputs
- 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.
- 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
|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:
- Click the Project tab, right-click the
Orchestration name, and click Start
Orchestration as shown in Figure 12.
Figure 12. Start CustomAPI orchestration
- 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
- 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.
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.
The authors would like to thank Raghavendra K. Neelekani for reviewing and providing valuable suggestions for this article series.
- WebSphere Cast Iron Information Center
- WebSphere Cast Iron Cloud Integration product page
- Integrating cloud applications with WebSphere Cast Iron Cloud Integration
- WebSphere Cast Iron Cloud Integration support
- Getting Started with IBM WebSphere Cast Iron Cloud Integration