Create an Integration on ICS to expose a REST API for a SOAP Connection for an external web service

In this article, I will show a little bit more of ICS – the Integration Cloud Service. In a previous article, I have introduced some concepts – such as Connection, Integration, Business Identifier. I have shown how to create an integration connecting two connections – an inbound and an outbound one (both of type SOAP).

In picture, that looks like this:

In this article, I will create a new connection (REST API style) and create an integration to expose this connection, leveraging the same outbound connection:

After creating the integration, I will activate it and invoke the new REST API from a web browser and from SOAP UI.

The steps are:

• Create REST Connection
• Create and activate the Integration (with the mappings for request and response and the business identifiers for tracking)
• Invoke the REST API

 

 

Configure REST Connection

Go to the ICS Home Page and navigate to the Connections page.

Create a New Connection.

Select REST as the Adapter Type for this new Connection.

Provide a name and description for the new REST Connection:

Press Create when done.

Click on the button Configure Connectivity.

A popup appears.

It is a bit unintuitive to configure the endpoint URL for an inbound connection. The documentation states that the protocol, host and port have to be set according to the URL of the ICS instance on which the connection is created and only the path segment following /integrations/ can be customized.

Set the endpoint to http://icsdem0058service-icsdem0058.integration.us2.oraclecloud.com/integrations/distanceConversion 

If that is the case – I would only want to have to – and be allowed to – specify that last part. I do not like to have to provide a URL that I cannot control. It is additional and meaningless work. It turns out to be even worse a little bit later on in this article: even the part of the URL that I can set to a custom value is not applied when the integration that exposes this connection is created later on.

Click OK to close the dialog.

Then click Configure Credentials

and specify that no security policy should be applied to this connection. We will find out later on that despite this configuration, we still need to provide [ICS Account] credentials when accessing the REST API from the internet.

Press OK to close the dialog.

Test the connection, save the details and click on Exit Connection.

 

Create the Integration

I will create a new integration that ties the REST Connection that was created in the previous section to an existing [outbound] SOAP Connection that references an external conversion Web Service; this connection was created in an earlier article on this blog.

Click on Integrations in the navigator on the left. Then click on Create New integration:

Select Map-my-Data as the Integration Pattern:

A dialog appears where you can provide a name and description for the new integration.

Note: the Identifier becomes part of the endpoint for the REST API.

Click on Create.

Drag the outbound connection from the list of Connections – to the Target area:

Provide a name for this endpoint and a nice description:

Click on Next.

Select the Port. Click Next again.

On the Summary Page, click Done.

Back in the integration editor, drag the new DistanceConversionREST connection to the Source area:

Now things get a little more interesting in the Configuration dialog that appears for this REST Connection Endpoint:

Provide the relative resource URL for the endpoint. This turns out to be the last part in the REST APIs URL.

In this case, I have entered: /distance/{source-unit}/{target-unit}

Here, distance is the name of the resource. The two string between curly brackets indicate template parameters – parameters whose value is passed in the URL path, for example: distance/Meters/Yards where Meters and Yards are the values for the two template parameters.

I have checked the checkbox to Configure this endpoint to receive the response. It seems that if you do not, any request to the endpoint will be regarded a fire-and-forget request that is asynchronously handled and does not return a response.

Click on Next.

In this page, the template parameters are further specified – by setting their data type. Additionally, query parameters can be added; these show up in the resource URL behind the question mark. For example: /distance/{source-unit}/{target-unit}?distance=1000.

I have added one query parameter, by clicking on the green plus sign. The parameter is called distance and is of type integer.

Click Next.

On the next page, the response payload is configured. The response can be of type XML or JSON. In this case, I have selected XML as the type of payload. I now need to specify the structure of the XML payload response. I can do that by uploading the XSD describing that XML payload.

The XSD document I have uploaded looks like this:

After uploading the XSD file and selecting the element that describes the response payload, press Next.

On the Summary page, after a final inspection, click Done.

The two ends of the integration have been configured. Now is the time to create the mappings – for the request flow and the response flow. First the request flow:

Click on the mapping icon, then on the plus icon.

Configure the mapping in straightforward way:

Click Save, then click Exit Mapper.

Click on the mapping icon for the response flow. Then click on the plus icon.

Map the elements from the ChangeLengthUnitResponse – the real response from the outbound connection – and from the original request message (here seen as the $SourceApplicationObject) to the response object that this mapping produces:

Click on Save and on Exit Mapping.

Back in the mapping editor, click on the Tracking icon. This brings up the Business Identifiers dialog where the tracking fields can be defined for this integration:

Click on Done.

Save the integration. Then click Exit Integration.

Back in the list with integrations, click on Activate to activate the new integration.

Confirm that detailed tracing should be enabled:

And we are done. The integration is ready for action.

 

Invoke the REST Endpoint to Convert some Distances

A REST API that supports the GET operation – as the API that was configured in this article does – can easily be invoked, just from a web browser for example.

The URL for the API’s endpoint can be looked up in the integration

Navigate to the Endpoint URL: https://icsdem0058service-icsdem0058.integration.us2.oraclecloud.com/integration/flowapi/rest/DISTANCECONVERSIONRESTUSINGEXTER/v01/metadata

The browser displays the login dialog – as this service is part of the ICS instance domain and requires an ICS account to access. I am not sure I completely like and understand this: I have specified that no security policy should apply to this API. Why then I still need to provide credentials is unclear.

After successfully logging in, the meta-data for the API is displayed:

Now I can execute the conversion by accessing the distance resource and providing the values for source unit and target unit (in the URL path segments) and distance (as query parameter). The URL can be like this:

https://icsdem0058service-icsdem0058.integration.us2.oraclecloud.com/integration/flowapi/rest/DISTANCECONVERSIONRESTUSINGEXTER/v01/distance/Meters/Yards?distance=100

The result is shown here:

The expected response in XML format is returned with the converted distance value.

In SoapUI, I can create a test project for this REST API. Provide the resource URL as a starting point:

I have added three parameters to this request – as shown below. One is a query parameter called distance, the others are template parameters whose names are not relevant. They are added to the Resource [URL]:

/integration/flowapi/rest/DISTANCECONVERSIONRESTUSINGEXTER/v01/distance/{source-unit}/{target-unit}

After defining the parameters, I execute the request.

As was to be expected, an HTTP 401 is returned, because the proper authentication details are not provided.

I switch to the Auth tab and add a new Authorization:

Add an authorization of type Basic:

Provide the same credentials as used before – belonging to an ICS account:

When I make the request again, this time I receive the hoped for response from the ICS REST API:

Let’s change the values of the three parameters – after inspecting the WSDL of the underlying external web service to figure out which values are supported for the source unit and target unit:

(and yes, that is of course not how it should be; the documentation for my REST API should list these values).

Finally, a brief glance at the Tracking tab of the ICS Monitor section, where the two most recents calls are clearly visible:

and each can be inspected for execution details:

Summary

Creating an integration to expose a REST API based on a SOAP connection [to an external third party web service] is fairly straightforward, as shown in this article. From the comfort of my own browser, I have defined the REST resource, the parameters and the mapping from the incoming HTTP GET request to the XML style response.

I would like more control over the endpoint of the API; perhaps by studying the documentation in more detail, I can find a way to control the URL. I particularly do not like defining the URL for the inbound connection: it has no meaning and is not used. Leaving it empty is not possible.

I also do not understand why this REST API that was specified without security policy would still require credentials. I would like to make REST APIs available to the anonymous public. Is that intentionally prohibited by ICS?