Introduction to Accessing Business Objects

About Accessing Business Objects

You can access business objects by making REST API calls enabled by the Oracle Business Object REST API framework.

In web applications, REST resources acted on by REST APIs are backed by business objects exposed in the visual development tool. For example, web application developers working with Oracle Visual Builder can decide on the set of attributes to expose on the business objects and the actions to make available (both standard CRUD operations and custom methods).

The design-time choices that you make when creating business objects allow the tooling to generate metadata that it uses to define REST resources and REST APIs. The data used by the web application is shaped by the resource's backing business object, with the parent-child relationships intact. Using these REST APIs exposed by the tooling, you may interact with business objects to access its data. As a result, your application may invoke CRUD operations to interact with the REST resources and business objects.

Use Cases and Examples

As a web application developer, working in an Oracle visual development tool like Oracle Visual Builder, you can generate REST API endpoints to manage and interact with the business objects of the application.

Here are the types of things that you can do using REST APIs to access the data of business objects:

Get a description of the REST resource, including the resource collection attributes and available actions.
Interact with the REST resource using standard HTTP request methods, including GET, POST, PATCH, and DELETE.
Allow the server to decide whether to create or update depending on whether the record exists or not.
Specify a framework version in a request to interact with the old format when the REST API Framework has made backward incompatible changes.
Perform advanced queries and sorting on a resource collection and shape the returned payload using URL parameters.
Use ETag for change detection and optimistic concurrency control.

To understand how certain design time features used to create web applications support the availability of these REST API capabilities, consult the Oracle documentation for your visual development tool.

About the Resource Samples in This Guide

This guide describes typical use cases for interacting with and manipulating business objects. All samples are based on DEPARTMENTS, EMPLOYEES, JOBHISTORY, and JOBS tables in the Oracle HR schema. This figure depicts the business objects generated from these tables in the web application.

Figure 1-1 Business Objects Used with REST APIs in this Guide

Description of "Figure 1-1 Business Objects Used with REST APIs in this Guide"

Understanding the REST API Framework

The Oracle Business Object REST API supports access to business objects. The Oracle Business Object REST API supports the exchange of information between the web application and server at runtime.

The Oracle Business Object REST API is an Oracle framework that allows web application developers to expose a REST API based on the REST architectural style. The framework itself does not constitute a Web API, but supports creating and interacting with the business objects. The REST API framework determines the functionality to interact with business objects created by web application developers.

In the web application, REST resources acted on by REST APIs are backed by business objects exposed in the web application. When you work in an Oracle visual development tool, like Oracle Visual Builder, you can decide on the set of attributes to expose from business objects and the actions to make available (both standard CRUD operations and custom object functions defined by the web application).

The design-time choices that you make are captured as metadata by the tooling, which the tooling uses to generate REST resource definitions. You may interact with these resource definitions through the REST API, supported by the REST API framework. For example, you may invoke CRUD operations to interact with the REST resources and business objects, where the data is shaped by the resource's backing business object, with the parent-child relationships intact.

Oracle releases may introduce new REST API framework functionality to support additional business object interaction use cases. To allow you to manage the level of functionality exposed to customers in your production applications, Oracle defines numeric versions of the framework that refer to a specific level of the REST API framework functionality. As Oracle introduces new Oracle Business Object REST API framework versions, you may opt into the new version to gain the new functionality, or you may decide not to opt in and instead preserve the level of functionality supported by the current REST API framework version.

Understanding Business Objects as REST API JSON Objects

REST APIs represent the business object as a JSON-encoded resource collection.

REST resource collections are synonymous with business objects created by web application developers. For example:

A Department resource collection is based on a Department business object.
An Employee resource collection is based on an Employee business object.

The payload returned by REST APIs contains one or more resource collections, comprised of the resource items queried by the REST API and the individual items of the business object. The resource collections preserve the relationship of master-detail coordinating business objects.

As the table below shows, the resource collection is the REST API payload representation of all items of a particular business object. The resource items are the rows and attributes of the payload item object, which represent the items of the business object.

Note:

The format of resource collections and contained items are defined by specific REST API media types as JSON-encoded entities. For more details, see Media Types.

Table 1-1 JSON Objects and Business Object Representation

JSON Object	Business Object
`resource collection`	A business object comprised of one or more items. `Department`, `Employee` are examples of resource collections that represent `Department` and `Employee` business objects.
`resource item`	An item of a business object. The specific department `10` or employee `1012` are examples of resource items that represent items of the `Department` and `Employee` business object.

Understanding Framework Support for Query Syntax

REST API calls can make use of a query expression syntax to query business objects.

Beginning with Oracle Business Object REST API framework version 2, REST API calls can make use of an expanded query expression syntax to query business objects. Note that version 2 and later will interpret the q query parameter value differently than framework version 1, and therefore opting into framework version 2 or later introduces a backward incompatible change to web applications that rely on framework version 1.

When you decide to opt into framework version 2 (or later), REST APIs calls will process fetch requests for the q query parameter using the expanded expression syntax, whereas requests using the version 1 “query-by-example” syntax will become invalid and will return an error. If you do not opt into framework version 2 or later, the default for your release version will be framework version 1. Alternatively, you may preserve the base functionality by creating a new release version identifier that you associate with framework version 2, while leaving the existing release identifier defined in the web application as framework version 1.

In version 1, filtering business object collections using query parameters is limited to a query-by-example syntax, which separates expressions using a semi-colon, as follows:

GET <base_url>/Department?q=Dname SA*;Loc BOSTON

Whereas, starting in version 2, a new advanced query syntax supports filtering business object collections using rowmatch expressions, as follows:

GET <base_url>/Department?q=Dname like 'SA*' or Loc = 'BOSTON'

Such expressions include the case-insensitive name of a resource item, followed by an operator and one or more operand values (depending on the operator used). The filter can be as simple as a single expression, or it can combine expressions using the and and or conjunctions with matching sets of parentheses for grouping.

Benefits of the Advanced Query Syntax Offered in Framework Version 2 and Later

The advantages of rowmatch expression include the following.

They may use supported operators:

DepartmentNumber = 20

DepartmentNumber <> 20

DepartmentNumber <= 20

DepartmentNumber < 20

DepartmentNumber >= 20

DepartmentNumber >20

DepartmentNumber between 20 and 40

DepartmentNumber not between 20 and 40

DepartmentNumber in (20, 30, 40)

DepartmentName like '%S%'

DepartmentName like 'RE%'

DepartmentName not like 'RE%'

Location is null

Location is not null
They may involve multiple attributes:

DepartmentNumber = 10 or DepartmentName like 'RESEARCH'

DepartmentNumber > 10 and DepartmentNumber < 40

DepartmentNumber < 20 or DepartmentNumber > 30

(DepartmentNumber = 10 or DepartmentNumber = 30) and (DepartmentName like 'SALES')

DepartmentNumber BETWEEN 20 and 40) and (Location like 'DAL%')

(DepartmentNumber > 0 and DepartmentNumber < 100) and (DepartmentName <> 'SALES') and (Location not like 'NEW%')

(DepartmentNumber = 10 or DepartmentNumber = 30) and (DepartmentName = 'ACCOUNTING' or DepartmentName = 'SALES')

(DepartmentNumber = 10 and DepartmentName like 'ACC%') or (DepartmentNumber = 20 and DepartmentName like 'RES%')

DepartmentName='ACCOUNTING' or (DepartmentName like 'R%' and Location like '%ALLA%')

(DepartmentName like 'R%' and Loc like '%ALLA%') or DepartmentName='ACCOUNTING'

(DepartmentName like 'R%' or Loc like '%ALLA%') or DepartmentName='ACCOUNTING'

(DepartmentNumber between 20 and 40) and DepartmentNumber is not null
They may involve attributes of nested child resources:

Deptno > 5 and Emps.Job = 'MANAGER'

Emps.Job = 'MANAGER' and Deptno > 5

Deptno > 5 and (Emps.Job = 'MANAGER')

(Emps.Job = 'MANAGER') and Deptno > 5

(Deptno > 5) and (Emps.Job = 'MANAGER')

(Deptno = 10 and Emps.Job = 'PRESIDENT') or (Deptno = 20 and Emps.Job = 'MANAGER')

Deptno > 5 and Emps.Job = 'MANAGER' and Emps.Sal >= 2500

Deptno > 5 and (Emps.Job = 'ANALYST' or Emps.Sal >= 4000)

(Deptno > 5 and Emps.Job = 'ANALYST') or Emps.Sal >= 4000

Emps.Job = 'ANALYST' or Emps.Job = 'SALESMAN'

Deptno > 5 and (Emps.Job = 'ANALYST' or Emps.Job = 'SALESMAN')

Deptno > 5 and Emps.Job = 'MANAGER' and Emps.DirectReports.Sal >= 2000

Deptno > 5 and (Emps.Job = 'MANAGER' or Emps.DirectReports.Sal >= 2000)

Deptno > 10 and (Emps.Job = 'MANAGER' and (Loc = 'NEW YORK' or Emps.Mgr=7698))

Deptno > 10 and (Emps.Job = 'MANAGER' or (Loc = 'NEW YORK' or Emps.Mgr=7698))

Deptno > 10 and (Emps.Job = 'MANAGER' or (Loc = 'NEW YORK' or Emps.Mgr=7698)) or Deptno = 40

Deptno > 10 and (Emps.Job = 'MANAGER' or (Loc = 'NEW YORK' or Emps.Mgr=7698)) or (Deptno = 40)

Deptno > 10 and (Emps.Job = 'MANAGER' or (Emps.DirectReports.Sal > 2000 and (Emps.DirectReports.Comm = 500 or Emps.DirectReports.Deptno > 10)))

Deptno > 10 and (Emps.Job = 'MANAGER' and (Emps.DirectReports.Sal >= 2000 and (Emps.DirectReports.Comm = 500 or Emps.DirectReports.Deptno > 10)))
They may involve the UPPER function:

UPPER(DepartmentName) = 'RESEARCH'

UPPER(DepartmentName) = UPPER('research')

UPPER(DepartmentName) like 'RES%' and UPPER(Location) like 'DAL%'

UPPER(DepartmentName) like UPPER('research')

Overview of the Advanced Query Syntax Offered in Framework Version 2 and Later

The following are specific expression use case examples.

To test whether a value is null you must use the is null or the is not null keywords:

AssignedToId is null

AssignedToId is not null

For equality use the = sign, and for inequality use either the != or the <> operators.

AssignedToId = 100000000089003

Priority != 1

Priority <> 1

ActivityType != 'RS'

ActivityType <> 'RS'

For relational comparisons, use the familiar <, <=, >, or <> operators, along with between or not between.

Priority <= 2

Priority < 3

Priority <> 1

Priority > 1

Priority >= 1

TotalLoggedHours >= 12.75

Priority between 2 and 4

Priority not between 2 and 4

For string matching, you can use the like operator, employing the percent sign % as the wildcard character to obtain "starts with", "contains", or "ends with" style filtering, depending on where you place your wildcard(s):

RecordName like 'TT-%'

RecordName like '%-TT'

RecordName like '%-TT-%'

To test whether a field's value is in a list of possibilities, you can use the in operator:

ActivityType in ('OC','IC','RS')

You can combine expressions using the conjunctions and and or along with matching sets of parentheses for grouping to create more complex filters like:

(AssignedToId is null) or ( (Priority <= 2) and (RecordName like 'TT-99%'))

(AssignedToId is not null) and ( (Priority <= 2) or (RecordName like 'TT-99%'))

When using the between or in clauses, you must surround them by parentheses when you join them with other clauses using and or or conjunctions.

Testing the REST API

You can test REST APIs to make requests and interact with the business objects outside of your web application development tool.

You use the visual development tool to create the web application and the business objects that your application interacts with. You use the endpoints generated by the development tool to test the REST APIs to access the business objects.

For example, you can use any of the following techniques to test the REST APIs:

In a 3rd party tool that you display in a browser
In the cURL command line tool from a command window
In a web browser (typically limited to GET requests)

Testing the REST APIs requires knowledge of the REST API URI syntax. For details about URI syntax, consult the Oracle documentation for your visual development tool.