• 22 Aug, 2026
• 0 Comments
• 10 Mins Read

How to Create REST API in OIC: A Complete Step-by-Step Guide

Create REST API in Oracle Integration Cloud (OIC): A Complete Step-by-Step Guide

Introduction

Modern applications rarely work in isolation. They need to communicate with databases, SaaS applications, mobile apps, web applications, and external systems. REST APIs provide a simple and flexible way for these systems to exchange data over HTTP.

Oracle Integration Cloud (OIC), now part of Oracle Integration, provides a low-code/no-code platform for designing, exposing, securing, and managing integrations. One of its commonly used capabilities is creating a REST API endpoint that can receive requests from external applications and return a response.

In this guide, we will learn how to create a REST API in OIC, configure the request and response structure, implement the integration logic, activate the integration, and test the API.

What Is a REST API?

REST stands for Representational State Transfer.

A REST API allows applications to communicate using standard HTTP methods such as:

• GET – Retrieve data
• POST – Create or submit data
• PUT – Update existing data
• PATCH – Partially update data
• DELETE – Delete data

For example, an employee application might expose:

GET    /employees
GET    /employees/{id}
POST   /employees
PUT    /employees/{id}
DELETE /employees/{id}

When an application sends a request to the REST endpoint, OIC can receive the request, process the data, invoke another application or database, and send an appropriate response.

Why Create a REST API in OIC?

Creating REST APIs in OIC is useful when you need to:

• Expose integration functionality to external applications
• Connect applications using HTTP/REST
• Receive JSON or XML requests
• Transform data between different systems
• Call databases, SaaS applications, and other APIs
• Apply authentication and security
• Build reusable integration endpoints
• Monitor API-based integrations

For example:

Client Application
        |
        | REST Request
        v
   OIC REST API
        |
        v
   Data Transformation
        |
        v
 Oracle Database / SaaS / External API
        |
        v
   OIC Response
        |
        v
 Client Application

Prerequisites

Before creating the REST API, you should have:

1. Access to an Oracle Integration instance.
2. Permission to create integrations.
3. Basic understanding of REST APIs.
4. Familiarity with JSON and HTTP methods.
5. A target system if your API needs to retrieve or send data.

For this example, we will create a simple Employee REST API.

Step 1: Log In to Oracle Integration

Log in to your Oracle Cloud account and open your Oracle Integration instance.

From the Oracle Integration home page, navigate to:

Design → Integrations

The Integrations page allows you to create and manage integration flows.

Step 2: Create a New Integration

Click:

Create → Integration

OIC provides different integration patterns depending on your requirement.

For a REST API, select an App Driven Orchestration pattern when the integration needs to be triggered by an external application through an API request.

Provide a meaningful name.

For example:

Employee REST API

You can also provide an identifier such as:

EMPLOYEE_REST_API

Add an optional description:

REST API to receive employee requests and return employee information.

Click Create.

Step 3: Configure the REST Trigger

After creating the integration, you will see the integration canvas.

The first important step is configuring the REST Adapter.

Click the REST Adapter on the trigger side.

The REST Adapter configuration wizard will open.

The configuration normally includes details such as:

• Endpoint configuration
• HTTP method
• Relative resource URI
• Request payload
• Response payload
• Security configuration

Step 4: Configure the Endpoint

Suppose we want to create the following API:

GET /employees/{employeeId}

The relative resource URI can be configured as:

/employees/{employeeId}

Here, employeeId is a path parameter.

For example:

/employees/101

In this request:

101

is the employee ID.

The REST API URL will contain the OIC integration endpoint along with the configured resource path.

Step 5: Select the HTTP Method

Select the appropriate HTTP method.

For retrieving employee information, choose:

GET

For creating a new employee, you could use:

POST

For updating an employee:

PUT

For deleting an employee:

DELETE

The HTTP method should match the business operation performed by your integration.

Step 6: Configure Request Parameters

If your API uses a path parameter such as:

/employees/{employeeId}

OIC recognizes employeeId as a parameter.

For example:

GET /employees/101

The value received by OIC is:

employeeId = 101

This value can then be mapped to a database query, SaaS API request, or another downstream service.

Step 7: Configure the Request and Response

A REST API usually exchanges data in JSON format.

For example, an employee request might look like:

{
  "employeeId": 101
}

An employee response could be:

{
  "employeeId": 101,
  "employeeName": "John",
  "department": "IT",
  "location": "Pune"
}

When configuring the REST Adapter, you can define the request and response structures using sample JSON/XML payloads or schemas, depending on the API configuration.

A well-defined request and response structure makes mapping and testing easier.

Step 8: Add Integration Logic

Once the REST trigger is configured, the next step is to implement the business logic.

For example:

REST Request
     |
     v
Extract Employee ID
     |
     v
Call Oracle Database
     |
     v
Retrieve Employee Details
     |
     v
Map Database Response
     |
     v
Return REST Response

OIC provides adapters and integration actions that allow you to connect to different systems.

Depending on your requirement, you could invoke:

• Oracle Database
• Oracle Fusion Applications
• Salesforce
• SAP
• REST APIs
• SOAP Web Services
• FTP/SFTP
• Object Storage
• Other SaaS and enterprise applications

Step 9: Add an Invoke Connection

Suppose employee information is stored in an Oracle Database.

You can add a database connection using the Oracle Database Adapter.

On the integration canvas:

REST Trigger → Oracle Database Invoke

Configure the database operation.

For example, the database query might logically retrieve employee information using:

SELECT employee_id,
       employee_name,
       department,
       location
FROM employees
WHERE employee_id = :employee_id;

The exact SQL configuration depends on how your database connection and integration are designed.

Step 10: Map the Data

After configuring the invoke, you need to map the REST request to the database request.

For example:

REST employeeId
       |
       v
Database employee_id

Then map the database response to the REST response:

Database employee_id    → REST employeeId
Database employee_name  → REST employeeName
Database department     → REST department
Database location       → REST location

OIC provides a graphical mapper for performing these transformations.

Step 11: Configure the REST Response

The final step in the integration flow is returning a response to the client.

For example:

{
  "employeeId": 101,
  "employeeName": "John",
  "department": "IT",
  "location": "Pune"
}

The client receives this response after OIC completes the integration flow.

Example Complete Integration Flow

A simple employee REST API can look like this:

             External Application
                     |
                     |
                GET Request
                     |
                     v
             +---------------+
             |  OIC REST API |
             +---------------+
                     |
                     v
             Extract employeeId
                     |
                     v
             +---------------+
             | Oracle DB     |
             | Invoke        |
             +---------------+
                     |
                     v
             Employee Details
                     |
                     v
                Data Mapping
                     |
                     v
             +---------------+
             | REST Response |
             +---------------+
                     |
                     v
             External Application

Step 12: Validate the Integration

Before activating the integration, validate the configuration.

Check:

• REST endpoint configuration
• HTTP method
• Request schema
• Response schema
• Adapter configuration
• Data mappings
• Required parameters
• Business logic
• Error handling

Correct any validation errors reported by OIC.

Step 13: Save and Activate the Integration

After completing the configuration:

1. Click Save.
2. Validate the integration.
3. Activate the integration.
4. Confirm the activation.

After activation, OIC generates an endpoint that can be used by client applications.

The endpoint will typically resemble:

https://<OIC-instance>/ic/api/integration/v1/flows/rest/<API-ENDPOINT>

The exact URL depends on your Oracle Integration environment and integration configuration.

Step 14: Test the REST API

You can test the API using tools such as:

• Postman
• cURL
• REST clients
• Application code

For example, using cURL:

curl -X GET \
"https://<OIC-instance>/ic/api/integration/v1/flows/rest/EMPLOYEE_REST_API/1.0/employees/101"

If authentication is required, include the appropriate authentication mechanism configured for your OIC endpoint.

Example Response

If employee ID 101 exists, the API might return:

{
  "employeeId": 101,
  "employeeName": "John",
  "department": "IT",
  "location": "Pune"
}

If the employee doesn’t exist, your integration can be designed to return an appropriate response, such as:

{
  "errorCode": "EMPLOYEE_NOT_FOUND",
  "message": "Employee 101 was not found."
}

Creating a POST REST API in OIC

The same concept can be used to create a POST API.

For example:

POST /employees

The client can send:

{
  "employeeId": 101,
  "employeeName": "John",
  "department": "IT",
  "location": "Pune"
}

The OIC flow could be:

POST Request
     |
     v
OIC REST Trigger
     |
     v
Validate Request
     |
     v
Transform Data
     |
     v
Oracle Database
     |
     v
Insert Employee
     |
     v
REST Response

A successful response could be:

{
  "status": "SUCCESS",
  "message": "Employee created successfully",
  "employeeId": 101
}

GET vs POST REST APIs in OIC

Feature	GET	POST
Primary purpose	Retrieve data	Create/submit data
Request body	Usually not required	Commonly used
Parameters	Path/query parameters	Request body commonly used
Example	/employees/101	/employees
Typical response	Retrieved data	Creation/status response

REST API Security in OIC

Security is one of the most important considerations when exposing an integration as an API.

Depending on your requirements and OIC capabilities, you may configure authentication and authorization mechanisms such as:

• Basic Authentication
• OAuth-based authentication
• Client authentication
• API security policies

Never expose sensitive business APIs without appropriate security controls.

For production environments, consider:

• Authentication
• Authorization
• HTTPS
• Input validation
• Least-privilege access
• Secure credentials
• Error handling
• Monitoring and auditing

Error Handling in OIC REST APIs

A production API should not simply assume that every request will succeed.

Common problems include:

• Invalid input
• Missing parameters
• Authentication failure
• Database failure
• Timeout
• Downstream API failure
• Unexpected response
• Duplicate records

You can design fault handling so that the API returns meaningful responses.

For example:

{
  "status": "ERROR",
  "errorCode": "INVALID_REQUEST",
  "message": "employeeId is required."
}

This is much more useful to the consuming application than exposing a generic technical error.

Monitoring the REST API

After activation, OIC provides monitoring capabilities to track integrations.

You can monitor:

• Integration instances
• Successful executions
• Failed executions
• Processing times
• Errors
• Request/response details, subject to logging and security configuration

Monitoring is especially important in production environments because it helps administrators identify failed integrations and troubleshoot issues.

Best Practices for REST APIs in OIC

1. Use Meaningful API Names

Instead of:

REST_API_1

prefer:

EmployeeManagementAPI

Meaningful names make integrations easier to maintain.

2. Use Consistent Resource Names

Prefer:

/employees

instead of:

/getEmployeeData

REST resources should generally represent business entities.

3. Choose HTTP Methods Correctly

Use:

GET    → Retrieve
POST   → Create
PUT    → Update
PATCH  → Partial update
DELETE → Delete

4. Validate Input

Validate mandatory fields before invoking downstream systems.

For example:

employeeId must not be null

5. Implement Error Handling

Always consider what happens when:

• The database is unavailable.
• The requested record doesn’t exist.
• The request is malformed.
• A downstream API fails.

6. Avoid Hard-Coded Values

Use OIC configuration and appropriate lookups/properties where values may differ between environments.

7. Secure the API

Production REST APIs should use appropriate authentication and authorization mechanisms.

8. Keep Payloads Simple

Only return the information required by the consumer. Avoid unnecessarily large payloads.

Common Issues When Creating REST APIs in OIC

1. Incorrect Endpoint URL

Make sure the generated endpoint and relative resource URI are correct.

2. HTTP Method Mismatch

If the API is configured as POST but the client sends GET, the request will fail.

3. Invalid JSON

The request payload must match the expected structure.

4. Mapping Errors

Check the OIC mapper when fields are missing or incorrectly transformed.

5. Authentication Errors

Verify that the client is using the authentication mechanism expected by the REST endpoint.

6. Downstream System Failure

If the database or external API fails, inspect the OIC integration instance and fault details.

Real-World Use Case

Consider an organization that has an employee portal and an Oracle Database.

The portal needs employee information.

Instead of allowing the portal to directly connect to the database, the organization can expose a REST API through OIC:

Employee Portal
       |
       | HTTPS REST API
       v
Oracle Integration Cloud
       |
       | Database Adapter
       v
Oracle Database

The portal sends:

GET /employees/101

OIC receives the request, retrieves employee information from the database, transforms the response, and returns JSON.

This provides a controlled integration layer between the application and backend system.

REST API in OIC: End-to-End Summary

The complete process can be summarized as:

1. Create Integration
        ↓
2. Select App Driven Orchestration
        ↓
3. Configure REST Trigger
        ↓
4. Define Resource URI
        ↓
5. Select HTTP Method
        ↓
6. Define Request/Response
        ↓
7. Add Business Logic
        ↓
8. Configure Invoke
        ↓
9. Map Request and Response
        ↓
10. Add Error Handling
        ↓
11. Validate
        ↓
12. Activate
        ↓
13. Test with Postman/cURL
        ↓
14. Monitor Execution

Conclusion

Creating a REST API in Oracle Integration Cloud (OIC) is a practical way to connect external applications with enterprise systems through standardized HTTP interfaces.

With the OIC REST Adapter, you can expose endpoints, accept JSON/XML requests, transform data, invoke databases or SaaS applications, implement business logic, return structured responses, and monitor integration executions.

A well-designed OIC REST API should focus on clear resource naming, correct HTTP methods, proper request/response schemas, secure authentication, robust error handling, input validation, and monitoring.

Whether you are building an employee API, customer API, order-processing service, or an API for Oracle Fusion integration, OIC provides a centralized integration layer that simplifies connectivity between modern applications and enterprise systems.