Using REST APIs to manage Connections in OIC

Sun, 20 Jun 2021 06:10:00 +0000

In cases, when we have many connections created on the OIC instance, it becomes hard to manage connections using the OIC console. Also, to achieve automation, manually going and updating each and every connection is never a feasible task. OIC provides various REST APIs to fetch connection details, update connection properties and delete connections. With the help of these APIs, we can overcome such scenarios.

In this blog, we will be discussing how to use various OIC connections REST APIs. A postman collection in the public workspace, which contains some of the use cases for this and can be forked, updated, and used accordingly.

Below are various REST APIs, that are covered in this blog.

Retrieve Connections
Retrieve a Connection
Update a Connection
Test a Connection
Refresh Metadata for a Connection
Delete a Connection

In this blog, we will be using Postman to test and run various APIs. Below is the link to the Postman collection, which will be helpful to try and test different REST APIs.

Authentication for REST APIs 🔗

To invoke OIC connections REST APIs, BASIC AUTH can be used to authenticate and authorize calls. The user whose credentials are used to call these APIs must have access to edit the connection.

OAuth can also be used to authenticate to REST APIs. In this blog, we will be using Basic Auth to authenticate/authorize API calls.

1. Retrieve Connections 🔗

[GET] {oic_host}/ic/api/integration/v1/connections

{oic_host} - Host URL for OIC instance

This API lets to get all available connections available on the OIC instance. This API provides support for pagination also. The default number of connection information returned without using the limit query parameter is 101.

We can use the limit query parameter to limit the number of records returned. For example:

As in the above example, we have kept the limit as 5, if we want to get the next 5 connection details, we need to update the request as below

[GET] {oic_host}/ic/api/integration/v1/connections?limit=5 &offset=5

This will return the connections 6-10.

To make this response even more readable, we have added a Visual table using the Postman visualizer. Once you click the Visualize under the response the section after sending the request from this Postman collection, the below tabular representation is shown.

2. Retrieve a Connection 🔗

[GET]{oic_host}/ic/api/integration/v1/connections/ :id

{oic_host} - Host URL for OIC instance.

:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

This API lets you fetch connection details of a specific connection by adding Connection ID as a path parameter to the request URL.

To make this response even more readable, we have added a Visual table using the Postman visualizer. Once you click the Visualize under the response section after sending the request from this Postman collection, the below tabular representation is shown.

3. Update a Connection 🔗

[POST]{oic_host}/ic/api/integration/v1/connections/ :id

{oic_host} - Host URL for OIC instance.
:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

This API helps to update the connection properties of a particular connection in the OIC instance. Let’s take an example to update the REST Connection properties that include Base path and Basic Auth user credentials.

Request Headers: 🔗

X-HTTP-Method-Override: PATCH

Request:

{
 "connectionProperties": {
 "propertyGroup": "CONNECTION_PROPS",
 "propertyName": "connectionUrl",
 "propertyType": "URL",
 "propertyValue": "{{CONN_REST_URL}}"
 },
 "securityPolicy": "BASIC_AUTH",
 "securityProperties": [
 {
 "propertyGroup": "CREDENTIALS",
 "propertyName": "username",
 "propertyValue": "{{CONN_USERNAME}}"
 },
 {
 "propertyGroup": "CREDENTIALS",
 "propertyName": "password",
 "propertyValue": "{{CONN_PASSWORD}}"
 }
 ]
}

Here, {{CONN_REST_URL}} will be the base URL of the REST endpoint. {{CONN_USERNAME}} and {{CONN_PASSWORD}} will be the credentials for BASIC Authentication for invoking the REST endpoint.

4. Test a Connection 🔗

[POST]{oic_host}/ic/api/integration/v1/connections/:id/test

{oic_host} - Host URL for OIC instance.

:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

This API is an alternative to the TEST button on OIC Connection page for a particular connection. Below is an example of successful testing of a Connection.

5. Refresh Metadata for a connection. 🔗

[POST] {oic_host}/ic/api/integration/v1/connections/:id/metadata

{oic_host} - Host URL for OIC instance.

:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

Sometimes, we may cache metadata for a connection, and if for some reason metadata is changed but our connection is still referring to old metadata. This API can come in handy. Below is the sample invocation of REST API in postman to refresh the metadata of a connection.

6. Delete a Connection 🔗

[DELETE] {oic_host}/ic/api/integration/v1/connections/ :id

{oic_host} - Host URL for OIC instance.

:id - Connection ID of the connection in OIC instance, to be passed as the path parameter.

This API can be used to delete a connection available on the OIC instance. This API saves a lot of time to perform delete operations rather than going to UI and manually deleting a connection. All you need to know is the connection id of the connection. Below is an example of the successful deletion of Connection by triggering the API using Postman.

To Validate if the Connection is deleted or not we can use a retrieve a connection API and check if the connection is available or not.

References: 🔗

https://docs.oracle.com/en/cloud/paas/integration-cloud/rest-api/api-integrations-connections.html

Please share your valuable feedback in the comments section below 😊

POSTMAN on DecipherMiddleware

Using REST APIs to manage Connections in OIC

Authentication for REST APIs 🔗

1. Retrieve Connections 🔗

2. Retrieve a Connection 🔗

3. Update a Connection 🔗

Request Headers: 🔗

4. Test a Connection 🔗

5. Refresh Metadata for a connection. 🔗

6. Delete a Connection 🔗

References: 🔗