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

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:

image

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:

image

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.

image

Select REST as the Adapter Type for this new Connection.

image

Provide a name and description for the new REST Connection:

image

Press Create when done.

Click on the button Configure Connectivity.

A popup appears.

image

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

image

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.

image

 

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:

image

Select Map-my-Data as the Integration Pattern:

image

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

image

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:

image

Provide a name for this endpoint and a nice description:

image

Click on Next.

Select the Port. Click Next again.

image

On the Summary Page, click Done.

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

image

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

image

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.

image

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.

image

The XSD document I have uploaded looks like this:

image

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.

image

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:

image

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

Configure the mapping in straightforward way:

image

Click Save, then click Exit Mapper.

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

image

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:

image

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:

image

Click on Done.

Save the integration. Then click Exit Integration.

image

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

image

Confirm that detailed tracing should be enabled:

image

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

image

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.

image

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

image

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:

image

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:

SNAGHTML4c7c13

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}

image

After defining the parameters, I execute the request.

image

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:

image

Add an authorization of type Basic:

SNAGHTML4fc5b0

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

image

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

image

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:

image

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

image

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

image

and each can be inspected for execution details:

image

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?

8 Comments

  1. Milind July 4, 2017
  2. Ajay Nishad May 29, 2017
  3. Khaja Mohiuddin April 24, 2017
  4. bassant October 12, 2016
  5. DJ September 30, 2016
    • DJ September 30, 2016
    • Lucas Jellema October 1, 2016
      • DJ October 26, 2016