ICS to API Platform

I’ve been using the API Platform and Integration Cloud Service (ICS) for some time now.  Independently, they are powerful products but together they are even better.

Initially, most ICS use cases were SaaS to SaaS or an extension to an existing SaaS.  But more and more I’m seeing people use ICS in place of a standard service bus to do basic validation, enrichment, transformation and routing.

But how do you expose these ICS services using standard API methods?  Well, it isn’t too difficult to go into API Platform and define an API to point to the ICS service, but this could be quite tedious.

Luckily, all the Oracle products have an “API first” strategy, so it wasn’t too difficult to setup an ICS flow to automatically publish new services into the API Platform.

I decided to use a scheduler ICS flow to periodically look for new services and publish them to the API Platform.

The first thing to do was to get information about the ICS services.  This was easy using the API: http://docs.oracle.com/cloud/latest/intcs_gs/ICSRB/op-v2-integrations-get.html

Using the result, I was able to filter on integrations that were currently ACTIVATED and REST based.  I didn’t want to try and publish ICS integrations between SaaS apps.

I then compare the ICS service with existing API Platform services to avoid creating any duplicates:

Now I’m ready.  I have an ICS service that needs to be put into API Platform.  I have chosen to do quite a few things in the next steps.

I create the API and automatically set it to be in the “released” state.  This is needed in order to publish it into the developer portal.  I then set a “vanity” name and publish it to the developer portal.  The last step deploys this new API into a gateway.  In my case, I just publish into the first gateway I find.  All of these APIs are documented here:
http://docs-uat.us.oracle.com/cloud/latest/api-platform-cloud/APFRM/index.html
Note: This is an internal link until API Platform is officially released.

Hidden away in the CreateAPI step, I’ve defined some default values for the API service flow.  These include key validation and rate limiting.

Overall, this works quite well.  Whenever I create and activate a new REST service in ICS, an API is created, published and deployed automatically.

Here is a video showing this in action:

Lessons Learnt

I think it is important to document some lessons learnt in this exercise.

• Setup a mock service (Apiary is nice) and add these along the path to help with debugging.
• Start small and do incremental steps.  When things go wrong with the ICS flow, it can be difficult to debug if you’ve made too many changes.
• When using rest calls, setup some postman or curl steps to make sure the APIs behave exactly as documented.  Some are a bit sensitive to what data is or is not there.  I have some basic curl scripts that create API entries based on a few command line arguments.  Debugging in this environment was much easier than in ICS.
• Don’t be afraid of doing an integration export/modify/import.  It wasn’t too difficult to use this method to quickly move my flow around or insert xslt when the UI wouldn’t let me.
• The lack of a “copy-of” in the XSLT editor was frustrating.  Only “value-of” is exposed.  So, this forces you to map each field individually.  In some cases I did the export/modify/import to modify value-of to copy-of.  This then copied the entire tree structure.
• When setting up your rest services and defining the sample JSON, you do not need to supply all the fields.  I found it convenient to remove everything except what I really needed.   This made the mapping much easier.  The structure of the JSON must stay the same, but if you omit fields in your sample, they are dropped automatically.
• Keep an ICS monitoring window or tab open separately.  I find going from the monitoring tab to the developer tab cumbersome.  So, I just open a second ICS window and use it to monitor the flow look for errors.  When I find a problem, I switch back, deactivate and edit the flow.

I hope this helps others wanting to use ICS and API Platform together.

Here is the code sample.  Please rename it to ICS2APICS_01.00.0000.iar before trying to do an import.  After import, you’ll need to define the ICS and APICS connectors.

ics2apics_01-00-0000