Out-of-the-box, Oracle provides a bunch of REST endpoints available to interact with your Oracle Integration Cloud (OIC) instance or the components in which you have built. In this post, we will look at how we interact with an OIC integration using the available REST endpoints throughout it’s lifecycle. This post will not cover all available endpoints and ways to utilize, but rather the key use cases and those that I think are really useful! The full list of available endpoints can be found here.

OIC supports OAuth 2.0 authentication mechanism. Before you can get started using these APIs, you will need to ensure you have the appropriate details to authenticate, retrieve a token and use in your REST calls. For information on doing this, see the Oracle Documentation.

When you call any of the Oracle Integration REST endpoints, the response header returns one of the standard HTTP status codes defined here.

I should also point out that all of this activity can also be completed manually within the OIC service console but these endpoints are specifically useful if you want to script/automate the lifecycle processes

---

OIC Integration Endpoints

Get Integration Details

For the purposes of this post, I have created 2 very simple schedule-driven integrations. All of the REST endpoints that I will showcase are based upon these integrations for simplicity and familiarity.

• HELLO_WORLD
• HELLO_AMY

There are 2 options when it comes to retrieving details of integrations. Either, you can get details of ALL integrations at the same time or your can retrieve a SINGLE integration’s details.

Get all integrations

This endpoint retrieves information about all integrations ordered by the last updated time.

• Method: GET
• Endpoint: <<OICServiceURL>>/ic/api/integration/v1/integrations
• Headers:

Key	Value
Authorization	Bearer <<OAUTH_TOKEN>>

By default this endpoint will return 100 integration records (this is also the MAX) and the “hasMore” field represents if there are more integration details that have not been returned. Given, I have only created 2 integrations, the “hasMore” field displays as false. For illustrative purposes, I can alter the limit… lets set the limit (via a query parameter) to 1.

By doing this we can see that only 1 of the integration is returned and “hasMore” field has a value of true. I won’t go into detail here of what to do in this situation but at a high level, if you find yourself in this scenario, you will need to use a combination of the “limit” and “offset” parameters for paginating through the returned results. For example, offset=100&limit=99 indicates to list integrations starting at the 101^st item and contain 99 items. i.e, integration number 101-200

…….I digress, but this is useful and important to know and is not just limited to OIC REST endpoints but as a core API design principle across Oracle REST endpoint capability.

Get a single integration

This endpoint retrieves detailed information about the integration with the specified ID. The ID is made up of the INTEGRATION_IDENTIFIER and VERSION_NUMBER separated by the pipe symbol (“|”). Therefore in this example, the ID of my HELLO_WORLD integration is “HELLO_WORLD|01.00.0000”

Note – it is the same endpoint as before, but this time, specifying the integration ID

• Method: GET
• Endpoint: <<OICServiceURL>>/ic/api/integration/v1/integrations/<<integrationID>>
• Headers:

Key	Value
Authorization	Bearer <<OAUTH_TOKEN>>

Export an Integration

So, now I have my integrations defined, it’s probably time to export them and get them into a code repository. This is the approach we would also use to later import to a new test environment or production. To export the integration you can use the following method.

• Method: GET
• Endpoint: <<OICServiceURL>>/ic/api/integration/v1/integrations/<<integrationID>>/archive
• Headers:

Key	Value
Authorization	Bearer <<OAUTH_TOKEN>>

Note – the response type of this REST endpoint is application/octet-stream. I recently wrote a post on this topic here.

If, like me, you are using postman, you will see as per the below screenshot that the response looks a little bit like gobbledygook!! That is because the endpoint is returning a file with the filetype “.iar”. We can’t simply open an .iar file as it is an archive .. (try unzipping it and having a look around 🙂 ).

Note – you can save the postman response as a file using the “Save Response” option.

Delete an Integration

Let’s assume for now that I was just told that the integration I built is actually now out-of-scope (boo!), so I need to delete it. This endpoint deletes the integration with the specified ID. The ID is made up of the INTEGRATION_IDENTIFIER and VERSION_NUMBER separated by the pipe symbol (“|”). Therefore in this example, the ID of my HELLO_WORLD integration is “HELLO_WORLD|01.00.0000”.

Note – It is important to make sure that the integration you want to delete is not active. (See later in this post on how to deactivate an integration).

• Method: DELETE
• Endpoint: <<OICServiceURL>>/ic/api/integration/v1/integrations/<<integrationID>>
• Headers:

Key	Value
Authorization	Bearer <<OAUTH_TOKEN>>

In the below screenshot, you can see that the HELLO_WORLD integration was successfully deleted.

Import (add) an Integration

Remember the integration I built (HELLO_WORLD) which was made out-of-scope? .. well, you guessed it… it just came back in scope! (yay!). It’s a good job that I had exported it and stored in a code repository 🙂

This endpoint imports a new integration that was previously exported. To submit this import (add) request, the integration must not be present in the OIC instance. If the integration was imported before, we can use the import (replace) request – details later in this post.

• Method: POST
• Endpoint: <<OICServiceURL>>/ic/api/integration/v1/integrations/archive
• Headers:

Key	Value
Authorization	Bearer <<OAUTH_TOKEN>>

• Body (form data):

Key	Value
File	required file location path

Now, as you can see in the below screenshot, my integration is now available within the OIC service console again. (Both integrations remain in “CONFIGURED” status.

Activating/Deactivating an Integration

An integration is not really much use unless it has been activated. You can’t run/trigger the integration without having activated it already, therefore, it is good practice that once you have imported an integration to also activate it at the same time.

The same goes for deactivating an integration. You can edit an integration unless it has been deactivated. Note – if your integration has been scheduled you must deactivate the schedule before (or at the same time as) deactivating the integration.

Important: During activation, the version number matters. If integration ABC/01.00.0000 is activated and you go ahead with activating ABC/01.00.0001, then ABC/01.00.0000 integration would be automatically deactivated before ABC/01.00.0001 is activated based on your request. There would only be one activated integration in this case (it would be the latest version)…. HOWEVER, if ABC/01.00.0000 is currently activated and your request to activate ABC/02.00.0000, both integrations will be active at the same time – same goes for deactivating

• Method: POST
• Endpoint: <<OICServiceURL>>/ic/api/integration/v1/integrations/<<integrationID>>
• Headers:

Key	Value
Authorization	Bearer <<OAUTH_TOKEN>>
X-HTTP-Method-Override	PATCH

Body (raw: JSON) — for activating an integration:

{
    "status":"ACTIVATED"
}

Body (raw: JSON) — for deactivating an integration:

{
    "status":"CONFIGURED"
}

Import (replace) an Integration

The final endpoint of note is the ability to import an integration via replacement. This endpoint enables direct replacement of an integration without the need to delete it first. This is particularly useful when migrating/propagating changed integrations through environments. This endpoint can only update an existing integration with the same name that was exported previously.

• Method: PUT
• Endpoint: <<OICServiceURL>>/ic/api/integration/v1/integrations/archive
• Headers:

Key	Value
Authorization	Bearer <<OAUTH_TOKEN>>

• Body (form data):

Key	Value
File	required file location path