REST Adapter in OIC Guide

Share

Introduction

The REST Adapter in Oracle Integration Cloud (OIC Gen 3) is one of the most widely used components in modern cloud integrations. In real-world Oracle Fusion implementations, almost every integration—whether it involves HCM, ERP, SCM, or third-party systems—relies on REST APIs for communication.

As a consultant, you’ll frequently use the REST Adapter to expose integrations as APIs, consume external services, or connect with Oracle Fusion REST endpoints. Whether you’re building employee onboarding flows, invoice integrations, or supplier sync processes, mastering the REST Adapter is non-negotiable.

This article provides a deep, implementation-focused guide to help you understand, configure, and troubleshoot the REST Adapter effectively.

What is REST Adapter in Oracle Integration Cloud?

The REST Adapter in OIC allows you to:

  • Expose an integration as a RESTful web service

  • Consume external REST APIs

  • Perform CRUD operations (GET, POST, PUT, DELETE)

  • Handle JSON and XML payloads

In OIC Gen 3 (aligned with Fusion 26A), the REST Adapter comes with enhanced capabilities such as:

  • Native JSON handling

  • Improved schema inference

  • Better OAuth 2.0 support

  • Simplified endpoint configuration

Think of the REST Adapter as the gateway between OIC and external systems, including Oracle Fusion applications.

Key Features of REST Adapter

1. Multiple Operation Support

  • GET → Fetch data (e.g., retrieve employee details)

  • POST → Create records (e.g., create invoice)

  • PUT/PATCH → Update records

  • DELETE → Remove records

2. Flexible Payload Handling

  • Supports both JSON and XML

  • Automatic schema generation from sample payloads

3. Security Support

  • Basic Authentication

  • OAuth 2.0 (Client Credentials / Authorization Code)

  • API Key-based authentication

4. Query and Path Parameters

  • Supports dynamic query parameters

  • Enables path-based routing (e.g., /employees/{id})

5. Pagination Handling

Useful when integrating with Oracle Fusion APIs returning large datasets.

Real-World Integration Use Cases

Use Case 1: Employee Data Sync (HCM to Third-Party)

  • Fetch employees from Oracle Fusion HCM using REST API

  • Transform payload

  • Send to external payroll system

Use Case 2: Invoice Creation (External → ERP)

  • External system sends invoice data via REST

  • OIC receives request using REST Adapter (trigger)

  • Integration calls ERP SOAP/REST API to create invoice

Use Case 3: Supplier Data Integration

  • Scheduled integration calls supplier API

  • Uses REST Adapter to GET supplier data

  • Updates Oracle Fusion Procurement

Architecture / Technical Flow

A typical REST-based integration looks like this:

Client System → REST Adapter (Trigger) → OIC Integration → REST Adapter (Invoke) → Target System

Key Components:

  • Trigger REST Adapter: Exposes OIC as API

  • Invoke REST Adapter: Calls external API

  • Mapper: Transforms payload

  • Connections: Manage endpoints and security

Prerequisites

Before working with REST Adapter, ensure:

  • OIC Gen 3 instance is active

  • Required roles assigned:

    • ServiceDeveloper

    • ServiceAdministrator

  • REST endpoint details available:

    • Base URL

    • Authentication method

    • Sample request/response payload

Step-by-Step Build Process

Let’s build a sample integration:

Scenario: Receive employee data via REST and send it to an external system.

Step 1 – Create REST Connection (Trigger)

Navigate to:

Home → Integrations → Connections → Create

  • Select Adapter: REST

  • Name: REST_Employee_Trigger

  • Role: Trigger

  • Base URL: Leave blank (for trigger)

Configure Security:

  • Choose: No Security (for testing) or OAuth 2.0

Test Connection → Save

Step 2 – Create REST Connection (Invoke)

  • Name: REST_Employee_Invoke

  • Role: Invoke

  • Base URL: https://api.external-system.com

Configure:

  • Security: Basic Auth / OAuth

  • Test → Save

Step 3 – Create Integration

Navigate to:

Home → Integrations → Create → App Driven Orchestration

  • Select Trigger: REST_Employee_Trigger

Step 4 – Configure Trigger Endpoint

Define:

  • Resource Path: /employee

  • Method: POST

  • Request Payload: Sample JSON

Example:

{ “empId”: “E1001”, “name”: “John Doe”, “email”: “john@example.com” }

OIC will automatically generate schema.

Step 5 – Add Invoke REST Adapter

Drag and drop REST Adapter:

  • Select: REST_Employee_Invoke

  • Method: POST

  • Resource URI: /employees

Define request/response using sample payload.

Step 6 – Data Mapping

Use Mapper to map:

Source Field Target Field
empId employeeId
name fullName
email emailId

Step 7 – Activate Integration

  • Validate → Activate

  • Note the endpoint URL

Testing the Technical Component

Test Using Postman

POST Request:

POST https://oic-instance-url/ic/api/integration/v1/flows/rest/EMPLOYEE_FLOW/1.0/employee

Payload:

{ “empId”: “E2001”, “name”: “Alice Smith”, “email”: “alice@example.com” }

Expected Result:

  • Integration processes request

  • External API receives mapped payload

  • Response returned to client

Validation Checks:

  • Check instance tracking in OIC

  • Verify payload transformation

  • Validate response status (200/201)

Common Errors and Troubleshooting

1. 401 Unauthorized

  • Issue: Incorrect credentials

  • Fix: Verify OAuth token or Basic Auth

2. 404 Not Found

  • Issue: Incorrect resource URI

  • Fix: Validate endpoint path

3. Payload Mapping Errors

  • Issue: Missing required fields

  • Fix: Validate schema and mappings

4. Timeout Issues

  • Issue: External API slow

  • Fix: Increase timeout or optimize API

5. JSON Parsing Errors

  • Issue: Invalid payload format

  • Fix: Validate JSON structure

Best Practices

1. Use Named Connections

Avoid hardcoding endpoints. Use reusable connections.

2. Implement Fault Handling

Use scope and fault handlers to manage errors.

3. Secure APIs Properly

  • Use OAuth 2.0 instead of Basic Auth in production

  • Avoid exposing unsecured endpoints

4. Use Pagination for Large Data

Handle large datasets efficiently.

5. Version Your APIs

Example:

/v1/employees /v2/employees

6. Logging and Tracking

Enable tracking fields for easier debugging.

Real Consultant Tips

  • Always keep sample payloads from real systems, not dummy data

  • Use Postman collections for testing multiple scenarios

  • Maintain API documentation (Swagger/OpenAPI) for integrations

  • Avoid tightly coupling REST endpoints with business logic—use orchestration wisely

  • In Fusion integrations, always test with actual REST endpoints from Fusion APIs

Frequently Asked Questions (FAQs)

1. Can REST Adapter handle both JSON and XML?

Yes, REST Adapter supports both formats, but JSON is preferred in modern integrations.

2. What authentication methods are supported?

  • Basic Authentication

  • OAuth 2.0

  • API Key

3. Can we expose OIC integration as public API?

Yes, using REST Adapter as a trigger, you can expose integrations as APIs.

Summary

The REST Adapter in Oracle Integration Cloud is a foundational component for building modern, API-driven integrations. From exposing integrations to consuming external services, it plays a critical role in every Oracle Fusion implementation.

As a consultant, your efficiency depends on how well you design REST interactions—right from connection setup to payload transformation and error handling.

Mastering the REST Adapter means you can:

  • Build scalable integrations

  • Connect multiple systems seamlessly

  • Handle real-world enterprise scenarios confidently

For deeper understanding and official documentation, refer to:
https://docs.oracle.com/en/cloud/saas/index.html


Share

Leave a Reply

Your email address will not be published. Required fields are marked *