Fusion REST API Specific Concepts
Oracle Fusion REST APIs extend standard REST principles by providing
powerful query, filtering, and response optimization features.
These capabilities are designed for enterprise-scale integrations,
allowing developers to efficiently retrieve only the required data
when working with Oracle Fusion applications through platforms such
as Oracle Integration Cloud (OIC), Visual Builder Cloud Service (VBCS),
and custom middleware solutions.
Understanding these Fusion-specific concepts is critical for building
high-performance, secure, and scalable integrations.
1. Query Parameter (q)
The q parameter is one of the most important features
in Fusion REST APIs. It allows clients to apply filtering conditions
directly at the server level, ensuring that only relevant records
are returned.
This reduces unnecessary network traffic and improves overall
integration performance.
Basic syntax:
q=attributeName operator 'value'
Commonly used operators include:
- = or eq (equal to)
- <> or ne (not equal to)
- >, <, >=, <= (comparison operators)
- and, or (logical operators)
- co (contains), sw (starts with), ew (ends with)
Example:
GET /departments?q=DeptName='SALES'
The q parameter supports complex expressions,
including multiple conditions and case-insensitive searches,
making it suitable for advanced business filtering.
2. REST-Framework-Version Header
Certain advanced Fusion REST API features require explicitly specifying
the REST-Framework-Version header.
This header ensures backward compatibility and enables newer
query processing capabilities on the server.
- Required for advanced operators such as IN
- Mandatory when filtering on child resources
- Recommended for complex enterprise queries
Example header:
REST-Framework-Version: 4
Failing to specify this header may result in unsupported
query errors or incomplete results.
3. Finder Parameter
The finder parameter provides predefined,
server-side optimized queries that are created and maintained
by Oracle.
Unlike the generic q parameter, finders leverage
indexed database logic, making them faster and more efficient
for frequently used search patterns.
Finder syntax:
finder=FinderName;ParameterName=Value
Example:
GET /suppliers?finder=PrimaryKeyFinder;SupplierId=300000018868695
Finders are commonly used for:
- Primary key lookups
- Business unit specific searches
- Status or flag-based filtering
4. Fields Parameter
The fields parameter allows clients to control
which attributes are returned in the API response.
By limiting the response to only required fields, integrations
become faster and consume less bandwidth.
Parent resource fields:
fields=SupplierId,SupplierPartyId
Child resource fields:
fields=SupplierId,sites:SupplierSiteId,SupplierSiteName
The fields parameter is strongly recommended
for large datasets and batch integrations.
5. Expand Parameter
The expand parameter allows related child resources
to be included within a single API response.
- expand=all expands all child resources
- Specific child resources can be expanded selectively
Example:
GET /suppliers?expand=sites
While expand reduces the number of API calls, excessive usage
can significantly increase payload size. Selective expansion
is considered a best practice.
6. Links in Fusion REST API Responses
By default, Fusion REST API responses include a
links section containing metadata and
navigation references.
- self
- canonical
- lov
- latest
To fetch only List of Values (LOV) data:
GET /resource?links=lov
Links provide discoverability and help clients navigate
related resources without hardcoding URLs.
7. onlyData Parameter
The onlyData parameter controls whether metadata
such as links is included in the API response.
- true removes the links section
- false includes links (default behavior)
Example:
GET /employees?onlyData=true
Using onlyData=true is ideal for lightweight
integrations and batch processing where metadata is unnecessary.
8. Best Practices for Fusion REST API Usage
- Always use fields to minimize payload size
- Prefer finder for frequently used queries
- Apply pagination for large result sets
- Avoid expand=all unless absolutely required
- Specify REST-Framework-Version for advanced filtering
Conclusion
Fusion REST API specific concepts provide enterprise-grade tools
for building scalable, high-performance integrations.
By effectively using query parameters, finder, fields, expand,
and response controls, developers can optimize data retrieval,
reduce system load, and ensure reliable integration between
Oracle Fusion applications and external systems.