9 Use Oracle JET REST Data Provider APIs
Use Oracle JET's REST Data Provider APIs (RESTDataProvider
and RESTTreeDataProvider
) to send queries to JSON-based REST services and
fetch the resulting data to your app.
The RESTDataProvider
implements Oracle JET’s
DataProvider
interface while the
RESTTreeDataProvider
implements the
TreeDataProvider
interface. We’ll first describe
RESTDataProvider
as it is the foundation API to fetch data from
JSON-based REST services using the Fetch API. The RESTTreeDataProvider
builds on the RESTDataProvider
to retrieve hierarchical data.
About the Oracle JET REST Data Provider
Use RESTDataProvider
when you want to send query parameters
to the JSON-based REST service so that the subset of data that matches your query is
returned to the JET app rather than all data.
Use it, if, for example, you want to display a list of employees in
your app who match a certain criterion, such as members of a department. You
could fetch the full list of employees to your JET app where you query the
returned data before you display the data rows that match your criterion.
This is inefficient because you send a request for data that you don’t need.
Instead, using an instance of RESTDataProvider
, you
construct a request to the REST service that returns the appropriate subset
of data.
RESTDataProvider
accomplishes this through the use
of transforms
, which is a property option that you specify
when you initialize a RESTDataProvider
instance.
RESTDataProvider
has three
transforms
property options. These are
fetchFirst
, fetchByOffset
and
fetchByKeys
. These correspond to the three
available fetch methods on data providers. Each property option defines the
following functions:
request
: A function that creates a Request object to use for the Fetch API call to the the REST API. This is where any required query parameters for paging, filtering, and sorting can be applied to the URL which can then be used to create a request. Other request options, such asheaders
,body
andmethod
can also be added to the request if needed.response
: A function that extracts the data and other relevant values from the response body. The function must, at a minimum, return an object with adata
property that is an array of items of type D (generic passed intoRESTDataProvider
class). The generic typeD
corresponds to the type of the entries in the loaded data. For example, for personal information data, you may have entries of type string and number, as in the following entries:{ name: string, age: number }
.
The Oracle JET Cookbook includes a series of demos that show usage
of the RESTDataProvider
. The Overview demo shows you how to
initialize an instance of RESTDataProvider
using the
fetchFirst
method that includes request and
response functions. See REST
Data
Provider in the Oracle JET Cookbook and REST Data Provider in the Oracle® JavaScript Extension Toolkit (JET) API Reference for
Oracle JET.
About the Oracle JET REST Tree Data Provider
Use RESTTreeDataProvider
when you want to retrieve
hierarchical data from JSON-based REST services.
The main difference between RESTDataProvider
and
RESTTreeDataProvider
is that
RESTTreeDataProvider
exposes an additional instance
method, getChildDataProvider
, and a constructor option that
is also named getChildDataProvider
. They have different
signatures.
- Instance method's signature is
getChildDataProvider(parentKey: K): TreeDataProvider<K, D> | null
- Constructor option's signature is
getChildDataProvider(item: Item<K, D>): DataProvider<K, D> | null
The getChildDataProvider
method takes as an argument the key of
the parent node to create a child data provider for. It then returns a
RESTTreeDataProvider
instance that loads the
children of the parent node or null
if the node is a leaf
node. A leaf node is a node that cannot have child nodes.
If the key of the parent node that you pass to
getChildDataProvider
does not correspond to a
previously fetched item or is an item that metadata identifies as a leaf
node, getChildDataProvider
returns null
.
Note that calls to getChildDataProvider(parentKey: K)
internally call getChildDataProvider(item: Item<K, D>)
after retrieving the item corresponding to parentKey
.
Therefore, it is the constructor option that accesses the metadata of the
item corresponding to a node's key. Since the constructor option is defined
by the JET app, it is the JET app, and not
RESTTreeDataProvider
, that decides whether to
return null
or a DataProvider
instance.
This whole flow, which starts from the JET app returning metadata through
the fetch response transform, is a mechanism to give apps enough information
to determine whether a node has children or not.
Note too that in the Oracle JET Cookbook the leaf field name is based on the metadata provided by the cookbook’s mock server through the response transform. Your REST service is likely to use a different field name.
The metadata used by the Oracle JET Cookbook’s mock server is of type
{ key: K, leaf: boolean}[]
. This indicates whether
the corresponding node is a leaf node. This is useful when invoking
getChildDataProvider
. It returns
null
when the parent node is a leaf node.
Otherwise, the node renders with an expansion arrow in the
oj-tree-view
component even though it cannot have
child nodes.
One other thing to note is that create operations for the
RESTTreeDataProvider
need to use the
parentKeys
option. This can be seen in the
addChildNode
method of the Events demo in the
Oracle JET Cookbook entry for REST Tree Data Provider. See more detail about the parentKeys
option in Data Provider Add Operation
Event Detail of the Oracle® JavaScript Extension Toolkit (JET) API Reference for
Oracle JET.
The Oracle JET Cookbook includes a series of demos that show usage
of the RESTTreeDataProvider
API. The Overview demo shows
you how to create an instance of RESTTreeDataProvider
using
the getChildDataProvider
method. See REST Tree Data Provider. In addition to the demos in the Oracle JET Cookbook,
see also the entry for the REST Tree Data Provider in the Oracle® JavaScript Extension Toolkit (JET) API Reference for
Oracle JET.
Create a CRUD App Using Oracle JET REST Data Providers
Use the Oracle JET REST Data Provider APIs to create apps that perform CRUD (Create, Read, Update, Delete) operations on data returned from a REST Service API.
Unlike the Common Model and Collection APIs that we recommended you to use
prior to release 11, RESTDataProvider
and
RESTTreeDataProvider
do not provide methods such as
Collection.remove
or Model.destroy
. Instead you
use the Fetch API and the appropriate HTTP request method to send a request to the REST
service to perform the appropriate operation. In conjunction with this step, you use the
data provider's mutate
method to update the data provider instance.
Note:
The steps that follow make specific reference toRESTDataProvider
, but the general steps also apply to
RESTTreeDataProvider
. View the Events demo in the Oracle JET
Cookbook entry for REST Tree Data Provider to see an implementation of CRUD-type functionality that uses
RESTTreeDataProvider
. Note that the demos in the Oracle JET
Cookbook use a mock REST server, so operations and responses in an actual REST service
may differ from Cookbook demonstration.
Define the Data Model for REST Data Provider
Identify the data source for your app and create the data model.
Read Records
To read the records, define the Oracle JET elements that will read the records in your app's page.
The following sample code shows a portion of the html
file that
displays a table of records using the oj-table
element and the
data
attribute that references the dataprovider
.
In this example, the table element creates columns for Department Id
,
Department Name
, and so on.
<oj-table id="table" data="[[dataprovider]]"
columns='[{"headerText": "Department Id",
"field": "DepartmentId"},
{"headerText": "Department Name",
"field": "DepartmentName"},
{"headerText": "Location Id",
"field": "LocationId"},
{"headerText": "Manager Id",
"field": "ManagerId"}]'>
</oj-table>
Create Records
To add the ability to create new records, add elements to your HTML page that accept input from the user and create a function that sends the new record to the REST service.