About the BOSS REST Data Source Definition

Learn about the BOSS REST Data Source definition.

You can view a REST Data Source on the REST Data Source page as described in Editing a REST Data Source. A newly created BOSS REST data source data source has the following:

• Operations defined for all those the endpoint supports.

• A data profile reflecting all its attributes. If you chose Yes for the Discover References setting during REST Data Source creation, the new REST Data Source’s data profile will have:

  • Read-only attributes of the first level (1/many)-to-1 reference objects.

  • Where applicable, updateable accessor foreign key attributes your pages can use to assign or update the reference object by key.

• A root resource name assigned.

• A resource type properly configured.

Once defined, you can use a REST Data Source in any APEX region while building pages. You can also use it programmatically using the appropriate procedures and functions available in the APEX_EXEC package.

Tip: For more information, see BOSS REST Data Sources in PL/SQL.

Operations

If the endpoint supports them all, the maximum set of wizard created operations includes:

• GET rows with filtering, ordering, and pagination support

• GET row by resource key

• POST (insert)

• PATCH (update)

• DELETE

Data Profile

For REST Data Sources of the resource type Business Object/View or Search View the Data Profile contains a primary key column named APEX$RESOURCEKEY mapped to the BOSS REST service’s resource key that uniquely identifies each row. This ensures that all BOSS REST services work in a consistent way against any endpoint, including ones whose underlying business object has a single-attribute primary keys, a multiple-attribute primary key, or defines an alternative unique key as a resource key. These two business object endpoint data sources will also contain a column named APEX$ETAG mapped to the BOSS etag with selector $context.etag. Using this column is required to update or delete rows if the business object defines an attribute of type historyType='versionNumber'. The Data Profile also has appropriately defined columns for all other business object attributes.

Data Profile Column Annotations

In addition to a properly configured data type, format mask (for dates), and REST payload selector, each data profile column’s Additional Information field may include a comma-separated list of one or more of the following case-sensitive tag names used to optimize how APEX communicates with the BOSS REST endpoint. APEX’s Create REST Data Source Wizard can automatically infer most of them, with the exception of HasDefault and Subtype which need to be added manually as appropriate.

• RemotePK - Omit null remote primary keys from create payloads so the service defaults their values.

• ETag - Identifies a column as the row version indicator used by BOSS as the ETag value.

• One of the following, or neither if the attribute is always updateable:

  • CreateOnly - Exclude column from update payloads.

  • ReadOnly - Exclude column from DML payloads.

• HasDefault - Omit a null-valued column from create payload to prioritize the server-side default.

• Required - Not currently enforced but useful to be aware of (and possibly enforced by APEX in the future).

• Subtype - Exclude field from $fields list and from create/update payloads if null.

• Sortable - indicates that the column is sortable.

• AccessorFK - Indicates that the column is the accessor foreign key for assigning a reference object.

Data Profile Considerations

Some Fusion Applications business objects contain hundreds of standard attributes. If you have opted to discover references, then adding in the first level of related objects can produce a data profile with many hundreds of attributes. The first 150 will be marked as Visible = true and the remaining attributes will have false for that property. The Visible property of a Data Profile column controls whether it appears in the column list in App Builder when creating regions. Chances are very high that your APEX application does not need to work with all of these attributes, but the Create REST Data Source Wizard defines a Data Profile column for all of the attributes. Developers have two easy ways to streamline the amount of data that will be exchanged between the APEX engine and a particular BOSS REST data source:

• You can delete Data Profile columns you are sure you will never need.

• You can mark Data Profile columns as not Visible to the APEX engine, without having to delete them.

• You can ensure each region uses only the necessary columns, either deleting the others from the region’s column list, or alternatively commenting them out or setting their Server-side Condition to Never.

There is no precise upper-limit on the maximum amount of BOSS REST endpoint business object attributes you can work with in a single request, but in practice, trying to query the data of hundreds of attributes for a single region, you may encounter runtime exceptions. The actual limit will depend on the length of the attribute names involved and the total number of attributes participating in the query. After the BOSS REST Data Source is created, at any time you can adjust which data profile columns are Visible by editing the data source and visiting its Data Profile.

Resource Name Setting

Each BOSS REST Data Source has a Root Resource Name setting whose value gets automatically inferred by the Create REST Data Source Wizard. This setting identifies the case-sensitive name of the root resource for the endpoint.

When working with an endpoint, such as .../v1/employees, that defines a top level business object, such as an employee, the root resource name will match the name of the REST resource (for example, employees). However, when defining a BOSS REST service for a collection of related child objects such as Vacation Requests that are owned by an employee using an endpoint URL, such as .../v1/employees/:empid/vacationRequests, the root resource name of this Vacation Requests data source would also be employees since it is part of a tree of data that is owned by the root Employee object.