This chapter includes the following sections:
The ADF REST framework is an ADF Model framework that allows Fusion web application developers to expose a Web API based on the REST architectural style. The framework itself does not constitute a Web API, but supports creating and interacting with resources and RESTful web services based on ADF Business Components business objects. A consequence of being RESTful, is a REST API that allows client application developers to interact with exposed business objects.
In the Fusion web application, ADF REST resources acted on by RESTful web services are backed by view object instances exposed in the data model of the ADF Business Components Model project. ADF Business Components developers working in the ADF Model project can decide on the set of attributes to expose from backing view objects, the actions to make available (both standard CRUD operations and custom methods defined by either a view object interface or view row interface), and the view link relationships to preserve for the resulting resource.
The design-time choices made by ADF Business Components developers are captured in REST resource definition XML files. Web service client developers may interact with these resource definitions through the REST API supported by the ADF REST runtime framework. As a result, the consuming service client may invoke CRUD operations to interact with the REST resources and ADF business objects. The data is shaped by the resource's backing view object instance, with the parent-child relationships intact.
Any ADF Business Components developer working in the ADF Model project can publish ADF REST resources to contribute to the Fusion web application.
Specific runtime features of ADF REST framework that support the exchange of resource information by client and server include:
Interacting with the REST resource is supported by separate JSON-based media type structures for the resource, action execution, and the results of action execution.
Passing a custom header to specify the version of the ADF REST runtime framework that will be used to process requests. The version header allows service clients to override the default version declaration defined by the REST application. In JDeveloper release 12.2.1.2.0, versions 1, 2, 3 exist.
Interacting with the REST resource using standard HTTP request methods, including GET, POST, PATCH, and DELETE.
Executing an HTTP method using an X-HTTP-Method-Override header using a POST request method when client restrictions prevent the use of standard HTTP methods to interact with the REST resource.
Locating a REST resource item (such as a specific employee) or resource collection (such as an collection of all employees) is supported by REST-compliant URI path names based on resource names defined in the ADF Business Components Model project.
Obtaining a description of the REST resource, including the resource collection attributes and available actions, is supported by a specific media type and describe action.
Linking to a canonical REST resource is supported when a resource with a super set of updatable entities is defined. The canonical link supports alternate links for the backing view object.
Filtering of the REST resource is supported by query string parameters on the URI specified by the client to access the specific resource.
Encoding formats are supported on the REST resource to enable compression and decompression.
Content streaming of BLOB and CLOB attributes exposed by the REST resource is supported by the ADF REST framework.
Performing data consistency checks while invoking the RESTful web service is supported by the ADF REST framework. This capability uses version history in the database to enable clients to manage HTTP payloads according to updates in the resource itself.
Passing a custom header to specify the ADF REST framework version (for example, version 2) with which the ADF REST runtime will use to process the request. The ADF REST framework version permits service clients to opt into framework enhancements made by Oracle in subsequent releases of Oracle JDeveloper.
Authorizing users to access the REST resource is enabled by ADF Security permission grants.
Specific design time features of ADF REST framework that affect the availability of runtime functionality include:
Registering REST resources with an application-specific resource version name (or number) to support versioning of REST resources. REST resource versions are named in the adf-config.xml
file for the application.
Declaring a default ADF REST framework version for individual REST resources to ensure the ADF REST runtime executes requests using functionality offered by a particular ADF REST framework version. Declaring a particular framework version allows service clients to opt into framework enhancements made by Oracle in subsequent releases of Oracle JDeveloper. The default ADF REST framework version is declared in the adf-config.xml
file for the application. In JDeveloper release 12.2.1.2.0, versions 1, 2, 3 exist.
Defining List of Value (LOV) attributes on the view object backing the resource to expose LOV accessor links in the URL resource path.
Defining row finders to locate a resource using the row finder key value in the URL resource path.
Defining client methods on the view client interface or view row client interface to expose custom actions that may be invoked using a request payload on an HTTP method.
Defining view instance of the application data model using a super set of updatable attributes to expose canonical links in the URL resource path.
Configuring change-indicator attributes on the entity object backing the resource to enable data consistency checking when making requests to access resources on the server.
Configuring a custom content type on the BLOB or CLOB attribute of the view object backing the resource to support content streaming using a link exposed in the resource.
Configuring security to authenticate users before allowing access to the resource.
You may find it helpful to understand related Oracle ADF features before you start working with RESTful web services. Following are links to supporting functionality that may be of interest.
For details about ADF Business Components and creating an ADF Business Components Model project, see Getting Started with ADF Business Components.
For details about creating RESTful web services in the ADF Business Components project, including enabling LOV links, row finders, custom methods, canonical resources, change indicators, custom content types for LOB attributes, and security, see Creating ADF RESTful Web Services with Application Modules.
For details about using the ADF REST data control to design the user interface, see Creating ADF REST Data Controls from ADF RESTful Web Services.
This chapter describes typical use cases for interacting with and manipulating ADF REST resources. All samples are based on DEPARTMENTS, EMPLOYEES, JOBHISTORY, and JOBS tables in the Oracle HR schema. Figure 22-1 depicts the view objects generated from these table in the ADF Business Components model project.
Figure 22-1 REST Sample Project - ADF Business Components View Instances
As Figure 22-2 shows, the Model project and the business components it defines, includes the ADF REST resource definition files. JDeveloper also generates the RESTWebService project to enabling running and testing resources in JDeveloper.
Figure 22-2 REST Sample Application - ADF Business Components
As Figure 22-3 shows, the Departments
resource is backed by the DepartmentsView
view object and the child resource Employees
is enabled.
Figure 22-3 REST Sample Project - Application Module Data Model
As Figure 22-4 shows, the application defines three version release names. Each ADF REST resource is assigned to one of these version identifiers and accessed at runtime by the version release name. For example, several versions of the Employees
resource were created: one with a limited set of supported operations and another with a more complete set of operations.
Note that the order of the version identifiers determines the version sequence, with the most recent version appearing at the top of the list. In the REST samples, where multiple versions of the Employees
resource exist, the release name 11.2
identifies the latest version.
Figure 22-4 REST Sample Project - Resource Versions
As Figure 22-3 shows, the application module organizes the created resources by their assigned version release name. The Employees
resource is originally created in version 11.0
and then revised in subsequent versions 11.1
and 11.2
with the addition of new mandatory attributes. The Jobs
resource added in 11.1
supports create operations on the Employees
resource with LOV-enabled attributes.
Figure 22-5 REST Sample Project - Application Module Resource Names
As Figure 22-6 shows, the Departments
resource is backed by the DepartmentsView
view object and the child resources Employees
and JobHistory
are enabled.
Note that the name of the child resource Employees
is derived from the destination view instance name in the defining view link. In the sample, the destination view instance was renamed from EmployeesView1
to Employees
. This supports accessing the child resource using the name Employees
in the URL resource path instead of the default name EmployeesView1
.
Figure 22-6 REST Sample Project - Departments Resource
As Figure 22-7 shows, version 11.0
of the Employees
root resource is backed by the EmployeesView
view object. Because Employees
was created as root resource, it has no child resource accessors.
Figure 22-7 REST Sample Project - Employees Resource Version 11.0
As Figure 22-8 shows, the EmployeesView
view object has multiple resources defined in version 11.0
of the Employees
root resource. The HREmployees
and BenefitsEmployees
resource are backed by unique view object shaping definitions and each of these resource defines the Employees
resource as its canonical resource.
Figure 22-8 REST Sample Project - Canonical Employee Resource Version 11.0
As Figure 22-9 shows, version 11.1
of the Employees
root resource adds functionality, including a Create operation to enable creating resource items using the Jobs
resource for the LOV-enabled EmployeesView
attribute JobId
. At runtime, the Jobs
resource will supply values for the LOV-enabled attribute JobId
without requiring the context of a row. This version also enables subtype usages in the Employees
resource collection, where the JobId
attribute serves as the discriminator for the subtype resource. At runtime, the Employees
resource displays the commission attribute for employees with the SA_REP
(Sales Representative) job ID.
Figure 22-9 REST Sample Project - Employees Resource Version 11.1
As Figure 22-10 shows, version 11.2 of the Employees
root resource adds the EmpByEmailFinder
row finder to enable locating employees by their email address.
Figure 22-10 REST Sample Project - Employees Resource Version 11.2
AsFigure 22-11 shows, the EmployeesView
view object defines the LOV-enabled attribute JobId
. The LOV accessor resource returns the list of jobs by title, and presents them as choices for the corresponding job ID.
Note that JDeveloper intentionally does not expose LOV accessors in the resource definition. At runtime the ADF REST runtime automatically nests LOV accessor resources as children of the resource item's LOV-enabled attribute.
Additionally, Figure 22-11 shows support for creating a new resource item with a LOV-enabled attribute defined. The EmployeesView
associates a specific version of an LOV accessor resource (identified as v2:Jobs
) with the LOV-enabled attribute JobId
. At runtime, the Employees
resource describe exposes a link to the LOV resource. The POST request to create a resource item may be completed with the aid of the LOV resource, which relies on the view object LOV definition to return the correct values to the LOV-enabled attribute.
Figure 22-11 REST Sample Project - Employees LOV-Enabled Attribute
As Figure 22-12 shows, the EmployeesView
view object defines the EmpByEmailFinder
row finder. The row finder retrieves the employee using the employee's email address (Email
attribute) instead of the employee's ID.
Note that row finders are exposed on all versions of the resource by default. However, when the row finder key attribute is defined in a particular resource definition, then it will be mandatory to use the finder name in the URL resource path. Until the row finder key is explicitly defined in the resource definition, the URL resource path will require the key attribute (EmployeeId
in this sample).
Figure 22-12 REST Sample Project - Employees Row Finder
As Figure 22-13 shows, the EmployeesView
view object defines a custom content type image/png
on the Picture
attribute. This content type replaces the default application/octet-stream
content type definition for the attribute and will be the expected accept type when streaming the image content.
Figure 22-13 REST Sample Project - Employees BLOB Content Type
As Figure 22-14 shows, the EmployeesView
view object defines a custom service method multiplySalary
for use with the Employees
resource. Because the method is defined on the view row interface, it will be exposed as a custom action at the level of resource items (specific employees), not resource collections (all employees). Only methods defined on the view object client interface will operate on resource collections.
Figure 22-14 REST Sample Project - Employees View Row Interface Custom Method
As Figure 22-15 shows, the Departments
entity object defines the change-indicator attribute RelState
to enable support for data consistency checking. The editor for the attributes has the Change Indicator and History Column - version number fields enabled to configure the change indicator.
Figure 22-15 REST Sample Project - Departments Change Indicator Attribute
A Departments
resource is based on a DepartmentsVO
view instance and its accessor to an EmployeesVO
view instance.
An Employees
resource is based on an EmployeesVO
view instance.
At runtime, when an action of the RESTful web service is invoked, the payload returned by the service contains one or more resource collections, comprised of the row sets queried by the backing view objects and the individual attributes of the view object rows. The resource collections preserve the relationship of master-detail coordinating view instances.
As Table 22-1 shows, the resource collection is the RESTful web service payload representation of a view object instance. The resource items are the rows and attributes of the payload item object, which in turn correspond to view object rows.
Note:
The format of ADF resource collections and contained items are defined by specific ADF REST media types as JSON-encoded entities. For more details, see ADF REST Media Types.
Table 22-1 JSON Objects and ADF Business Component Representation
JSON Object | ADF Business Component |
---|---|
|
View object instance comprised of one or more rows. |
|
A view object row. The specific department |
The describe for the RESTful web service allows you to identify the shape and actions allowed on an ADF RESTful web service. It returns a JSON object that contains the attributes, actions, and links defined in the REST resource definition.
The ADF REST framework supports the following describe use cases for the service end point:
Describe all available resources (resource catalog).
Describe a single resource collection.
Describe a single resource item.
Describe a nested resource in a parent-child relationship.
To retrieve the describe, invoke an HTTP GET with /describe
appended to the resource URL.
Note:
Executing a GET request to retrieve a resource describe also requires the client to be in the context of a particular version. For information on how to get the version release names for the service end point, see Retrieving Resource Versions.
For example, the following URL returns the describe for the Employees
resource of version 11.0
in the identified application:
http://host:port/context-root/rest/11.0/Employees/describe
To retrieve the describe of all the resources of a specific version in the application, you append /describe
to the version URL.
For example, the following URL returns the describe for all resources of version 11.0
in the identified application:
http://host:port/context-root/rest/11.0/describe
ADF REST runtime supports describing all available resources for the application end point using a GET method.
To examine all available resources in the resource catalog:
Execute the resource catalog describe and locate the names of the resources in the describe. The children
attribute identifies nested resources.
Examine these resource objects to understand the shape of each resource:
attributes
specifies the list of available resource collection attributes.
collection
specifies the shape of the collection and specifies finder
for row finder, links
, and available actions
(including media types).
item
specifies the shape of the instances of the collection and itself specifies links
and available actions
.
children
specifies any nested resources (and itself contains attributes
, collection
, and item
objects).
Note:
You can use theinclude
query parameter for the catalog describe to include the description of resources of a certain visibility. For example, you can use http://server/demo/rest/v1/describe?include=all
. You can use all, unlisted, or public as value for the include
query parameter. You can use the values as comma-separated list like ?include=all, unlisted.
For more information on visibility, see How to Hide a Resource.
For example, the describe for a service with Departments
and child Employees
resources returns the following objects:
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { ... } ], "collection" : { ... } ], "finders" : [ { } ] "links" : [ { } ] "actions" : [ { } ] }, "item" : { "links" : [ { } ] "actions" : [ { } ] }, "children" : { "Departments" ... } ], ... "links" : [ { } ] } }
The following sample describes version 11.0
of all resources in the resource catalog. Note that the URL version parameter 11.0
may be replaced with an application-specific version identifier. For more details about specifying resource versions, see in Retrieving Resource Versions.
Request
URL
http://server/demo/rest/11.0/describe
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.description+json
Payload
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 24, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Employees/{id}/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Employees/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "children" : { "JobsLOV" : { "discrColumnType" : false, "attributes" : [ { "name" : "JobId", "type" : "string", "updatable" : false, "mandatory" : true, "queryable" : true, "precision" : 10 }, { "name" : "JobTitle", "type" : "string", "updatable" : false, "mandatory" : true, "queryable" : true, "precision" : 35 }, { "name" : "MinSalary", "type" : "integer", "updatable" : false, "mandatory" : false, "queryable" : true, "precision" : 6 }, { "name" : "MaxSalary", "type" : "integer", "updatable" : false, "mandatory" : false, "queryable" : true, "precision" : 6 } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "JobId", "type" : "string", "updatable" : false, "mandatory" : true, "queryable" : true, "precision" : 10 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Employees/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "replace", "method" : "PUT", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/describe", "name" : "canonical", "kind" : "describe" } ] }, "Departments" : { "discrColumnType" : false, "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 }, { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 30 }, { "name" : "RelState", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true } ], "collection" : { "rangeSize" : 24, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "testImpl", "parameters" : [ { "name" : "testid", "type" : "string", "mandatory" : false } ], "resultType" : "string", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "replace", "method" : "PUT", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "replace", "method" : "PUT", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }
The ADF REST runtime supports describing resource collections using a GET method.
To examine a resource collection:
Execute the resource collection describe and locate the names of the resources in the describe.
Examine these resource objects to understand the shape of each resource:
attributes
specifies the list of available resource collection attributes.
collection
specifies the shape of the collection and specifies finder
for row finder, links
, and available actions
(including media types).
item
specifies the shape of the instances of the collection and itself specifies links
and available actions
.
children
specifies any nested resources (and itself contains attributes
, collection
, and item
objects).
For example, the describe for the Departments
resource returns the following objects:
{ "Resources" : { "Departments" : { "discrColumnType" : false, "attributes" : [ { ... } ], "collection" : { ... } ], "finders" : [ { } ] "links" : [ { } ] "actions" : [ { } ] }, "item" : { "links" : [ { } ] "actions" : [ { } ] }, "children" : { "Employees" ... } ], ... "links" : [ { } ] } }
The following sample describes version 11.0
of the Departments
resource.
Request
URL
http://server/demo/rest/11.0/Departments/describe
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.description+json
Payload
{ "Resources" : { "Departments" : { "discrColumnType" : false, "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 }, { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 30 }, { "name" : "RelState", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true } ], "collection" : { "rangeSize" : 25, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "testImpl", "parameters" : [ { "name" : "testid", "type" : "string", "mandatory" : false } ], "resultType" : "string", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "replace", "method" : "PUT", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "replace", "method" : "PUT", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }
The ADF REST runtime supports describing a resource item using a GET method.
Note that a resource item describe typically provides the same information as the collection describe. In the case of a polymorphic collection, however, a resource item describe will have more information than a resource collection describe. Consider, for example, the polymorphic collection vehicles, where the vehicles resource contains an item automobile and an item airplane. The description of vehicles will return a general shape of all vehicles, whereas, a resource item describe of an automobile will return the specific shape of that object.
To examine a resource item:
Execute the resource item describe and locate the names of the resources in the describe. The children
attribute identifies nested resources.
Examine the resource item describe to understand its shape.
attributes
specifies the list of available resource collection attributes.
item
specifies links
to the item, including defined child collections, and available actions
.
links
specifies describe links.
For example, the describe for a Departments
resource item returns the following objects:
{ "Resources" : { "Departments" : { "discrColumnType" : false, "attributes" : [ { ... } ], "item" : { "links" : [ { } ] "actions" : [ { } ] }, "links" : [ { } ] } }
The following sample describes version 11.0
of an instance of the Departments
resource collection.
Note: To recursively include all children of the resource item on the requested describe, provide the query parameter ?includeChildren=true
on the describe URL.
Request
URL
http://server/demo/rest/11.0/Departments/10/describe
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.description+json
Payload
{ "Resources" : { "Departments" : { "discrColumnType" : false, "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 4 }, { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 30 }, { "name" : "RelState", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true } ], "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "replace", "method" : "PUT", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/describe", "name" : "canonical", "kind" : "describe" } ] } } }
The ADF REST runtime supports describing an ADF REST nested resource using a GET method.
To examine nested resources in the resource catalog:
Execute the nested resource describe and locate the names of the resources in the describe. The children
attribute identifies nested resources.
Examine these resource objects to understand the shape of each resource:
attributes
specifies the list of available resource collection attributes.
collection
specifies the shape of the collection and specifies finder
for row finder, links
, and available actions
(including media types).
item
specifies the shape of the instances of the collection and itself specifies links
and available actions
.
children
specifies the nested resources (and itself contains attributes
, collection
, and item
objects).
For example, the describe for the nested resources Departments
and Employees
returns the following objects:
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { ... } ], "collection" : { ... } ], "finders" : [ { } ] "links" : [ { } ] "actions" : [ { } ] }, "item" : { "links" : [ { } ] "actions" : [ { } ] }, "children" : { "Departments" ... } ], ... "links" : [ { } ] } }
The following sample (URL1) describes version 11.0
of the Employees
resource which can be found in the context of a Department
. The second sample (URL2), describes an item of the same nested resource Employees
, where the ID of the employee identifies the nested resource item.
Note: To recursively include all children of the resource item on the requested describe, provide the query parameter ?includeChildren=true
on the describe URL.
Requests
URL 1
http://server/demo/rest/11.0/Departments/10/child/Employees/describe
URL 2
http://server/demo/rest/11.0/Departments/10/child/Employees/200/describe
HTTP Method
GET
Content-Type
none
Payload
none
Responses
HTTP Code
200
Content-Type
application/vnd.oracle.adf.description+json
Payload 1
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { "rangeSize" : 25, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ] }, { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "replace", "method" : "PUT", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } }
Payload 2
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobTitle", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "replace", "method" : "PUT", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "multiplySalary", "parameters" : [ { "name" : "multiplicand", "type" : "number", "mandatory" : false } ], "resultType" : "number", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.action+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ] } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200/describe", "name" : "canonical", "kind" : "describe" } ] } } }
links
is a JSON object where the value is always a URL link and the link name is defined according to the rel
of the link. The links
object is generated for each resource collection, item, and for the resource itself.
Note that URL links in the resource describe will be generated using a template placeholder value ({id}
) when there is not enough information to determine all parts of the URL. For example, the following child link provides a URL with the placeholder for the value of the specific Department resource:
"item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" }
The rel
attribute defines the type of link relationship between the current resource and the resource which the link points to. Relationships may be specified by any of the values shown in Table 22-2.
Table 22-2 Link Relationship in ADF REST Resource Describe
Link Relationship | Description |
---|---|
|
Always generated for a resource. The |
|
Always generated. The |
|
Always generated for a nested resource. The |
|
Generated when the resource has nested children. The |
|
Generated on a resource item for LOV-enabled (list of values) attributes. There are two types of The first type is defined in the model project by an LOV view accessor and an LOV-enabled attribute backing the resource item. The second type is defined in the model project by an LOV resource on the LOV view accessor and the resource is associated with the LOV-enabled attribute backing the resource item. |
|
Generated for BLOB and CLOB attributes by default. This relationship indicates that the link points to a resource that cannot be represented with the supported payload types. An image, that cannot be represented in JSON, is an example of this relationship. |
|
Generated for a resource that exists outside of the framework domain. |
|
Generated in the resource version describe when multiple resource version identifiers exist. The |
|
Generated in the resource version describe when multiple resource version identifiers exist. The |
|
Generated in the resource version describe when multiple resource version identifiers exist. The |
|
Generated in the resource version describe. The |
The href
attribute defines the URL to the linked resource or resource describe.
The cardinality
attribute is an optional attribute that defines the cardinality between the source resource and the destination resource. This attribute will be available only when the rel
attribute value is child
and the resource type is vnd.oracle.adf.description+json
. This cardinality attribute has the following attributes.
value
: The value of the cardinality. Example: "1 to *
"
sourceAttributes
: The attribute in the source resource used to link to the destination resource.
destinationAttributes
: The attribute in the destination resource used to link to the source resource.
In JDeveloper, ADF REST resource developers create version identifiers and associate these identifiers with the resources they create. The use of the version identifier allows the REST resource developer to manage updating an existing resource definition. When a resource needs to be updated with a change that is not backward compatible with the previous version, the resource developer may create a new version of the resource and assign it a unique version identifier.
The ADF REST runtime supports getting the versions defined in the application, which can include retrieving all available versions, just the latest version, or only a specific version.
Additionally, the REST resource developer can assign a lifecycle status (active
, desupported
, deprecated
) when they create or update a version identifier. Resources that have been tagged deprecated
are handled as valid resources and that status has no runtime impact. Whereas, resources that have been tagged with the lifecycle status desupported
will no longer be accessible by the service client and requests for desupported versions will return the following error message:
JBO-29151: The requested version 'x' has been desupported.
If the service client requests a resource that does not exist for the requested version, the ADF REST runtime will fallback to a previous version with status active
or deprecated
. Thus, if the Departments
resource versions 11.0
and 11.1
exist but 11.2
does not, the request for version 11.2
will return the next more recent resource, version 11.1
.
The ADF REST runtime supports retrieving the version release names defined for the service end point using a GET method.
To examine the version release names:
Execute the service end point describe and locate the available version release names in the describe.
Examine these elements to understand the order of the release name version identifiers:
version
specifies the release name of the version identifier as defined in the adf-config.xml
file.
isLatest
property specifies the version is the most recent version identifier.
predecessor-version
specifies the link to the previous version identifier.
successor-version
specifies the link to the next latest version identifier.
current
specifies the link to the most recent version identifier.
For example, the describe for a service end point with two version release name identifiers returns the following objects:
{ "items" : [ { "version" : "version_identifier_latest", "isLatest" : true, "links" : [ { "rel" : "self", ... }, { "rel" : "canonical", ... }, { "rel" : "predecessor-version", ... }, { "rel" : "describe", ... } ] }, { "version" : "version_identifier_previous", "links" : [ { "rel" : "self", ... }, { "rel" : "canonical", ... }, { "rel" : "successor-version", ... }, { "rel" : "describe", ... } ] } ], "links" : [ ... { "rel" : "current", ... } ] }
The following sample retrieves all available version release name identifiers defined in the resource catalog of the demo
application. In the sample, the three version identifiers are 11.0
, 11.1
, and 11.2
, where 11.2
is the current (or most recent) version. Note that links of type predecessor-version
and successor-version
specify the location of each version relative to their position in the list of versions.
Request
URL
http://server/demo/rest
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.description+json
Payload
{ "items" : [ { "version" : "11.2", "isLatest" : true, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/11.1", "name" : "predecessor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.2/describe", "name" : "describe", "kind" : "describe" } ] }, { "version" : "11.1", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/11.0", "name" : "predecessor-version", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/11.2", "name" : "successor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.1/describe", "name" : "describe", "kind" : "describe" } ] }, { "version" : "11.0", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0", "name" : "canonical", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/11.1", "name" : "successor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.0/describe", "name" : "describe", "kind" : "describe" } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest", "name" : "self", "kind" : "collection" }, { "rel" : "canonical", "href" : "http://server/demo/rest", "name" : "canonical", "kind" : "collection" }, { "rel" : "current", "href" : "http://server/demo/rest/11.2", "name" : "current", "kind" : "item" } ] }
The ADF REST runtime supports retrieving a specific version of the resource using a GET method. The specific resource version is one that has been associated at design time with the resource. Release version identifiers are defined in the Release Version page of the adf-config.xml
overview editor.
The following samples describe two versions of the Departments
resource. The first resource describe (request 1) returns version 11.0
and the second resource describe (request 2) returns version 11.1
. The resource describe for 11.1
shows additional mandatory attributes HireDate
and PhoneNumber
have been defined on the resource.
Request Version 1
URL 1
http://server/demo/rest/11.0/Departments
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.describe+json
Payload 1
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] } ], "collection" : { ... } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { ... } ] }, "item" : { "links" : [ { ... } ], }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } }
Request Version 2
URL 2
http://server/demo/rest/11.1/Departments
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.describe+json
Payload 2
{ "Resources" : { "Employees" : { "discrColumnType" : false, "title" : "Employees All Attributes", "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10 }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 4 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 8, "scale" : 2 }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "replace", "method" : "PUT", "requestType" : [ "image/png" ] }, { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "image/png" ] } ] }, { "name" : "HireDate", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true }, { "name" : "PhoneNumber", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 } ], "collection" : { ... } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { ... } ] }, "item" : { "links" : [ { ... } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } }
The ADF REST runtime supports the following GET method use cases:
Fetching a resource collection.
Fetching a paged resource collection.
Filtering a resource payload using primary key finder parameters.
Filtering a resource payload using query parameters.
Fetching a resource item.
Fetching nested child resources.
Fetching a sorted resource collection.
The ADF REST runtime supports fetching a resource collection using a GET method.
The following sample fetches version 11.0
of the Departments
resource collection and five items.
Request
URL
http://server/sample/rest/11.0/Departments
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 5, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
The ADF REST runtime supports retrieving resource collections with row set pagination using a GET method. Paging a resource collection with the GET method is performed using the following URI query parameters:
limit restricts the number of resources returned inside the resource collection. If the limit exceeds the resource count, then the framework will return all available resources. The value is the maximum number of resources to be returned.
offset defines a zero-based index into the collection (where 0 is the first position). The index identifies the starting position of the resource collection. If offset exceeds the resource count, then no resources are returned.
In the following sample, where a Departments
resource collection has five items, the first request (URL1) retrieves two items (at index 0 and 1), and because offset
is omitted, the starting position of the response is the first item. To display another set of resource items, a second request (URL2) may be made with an offset
of 2
to correspond to the third item and a limit
of 2
to retrieve only two more items (at index 2 and 3), and the last request (URL3) with an offset
of 4
returns the last item of the five item resource collection (at index 4).
Each time a new set of resource items is retrieved, the hasMore
attribute of the response indicates whether more items may be returned from the collection. In this example, because the collection contains only five items, the response for URL3 shows hasMore
set to false
, indicating that the last set of items had been retrieved.
Note that when the limit
parameter is omitted from the paging URL, the ADF REST runtime assumes a limit
of 25
(as determined by the default RangeSize
value on the resource's iterator binding definition). In this case, up to twenty-five items will be returned with each request. For this reason, it is a best practice when paging through a collection to always include the limit
query parameter to ensure only the desired number of resource items are returned and not more.
Requests
URL 1
http://server/demo/rest/11.0/Departments?limit=2
URL 2
http://server/demo/rest/11.0/Departments?offset=2&limit=2
URL 3
http://server/demo/rest/11.0/Departments?offset=4&limit=2
HTTP Method
GET
Content-Type
none
Payload
none
Responses
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload 1
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : true, "limit" : 2, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
Payload 2
{ "items" : [ { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : true, "limit" : 2, "offset" : 2, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
Payload 3
{ "items" : [ { "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 1 "hasMore" : false, "limit" : 25 "offset" : 4, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
The ADF REST runtime supports fetching a resource collection using a GET method and a fixed URL that includes a finder defined by one or more primary key attributes of the resource. Every view object upon which the resource is based defines at least one primary key attribute. The ADF REST runtime supports passing primary key values in the finder query string to filter the collection.
Filtering with a primary key (PK) is performed using the finder query string to specify one or more primary key values. The finder with primary key query string parameter format is:
finder=PrimaryKey;<PKattr1>=<PKvalue1>,<PKattr2>=<PKvalue2>,...
For example, a resource collection Employees defines the primary key attribute EmployeeId
. To filter the collection using the primary key finder for a specific employee, the finder query string may be specified as the following example shows.
finder=PrimaryKey;EmployeeId=101
When the resource is defined by a multi-part primary key, the finder allows you to pass the corresponding number of primary key values to filter the collection. For example, a resource collection Inventory might have ProductId
and WarehouseId
as its primary key attributes. To filter the collection using the primary key finder for a specific inventory item, both primary key values must be supplied in the finder query string as the example below shows.
finder=PrimaryKey;ProductId=8568,WarehouseId=45
The resource collection describe explains the finder and primary key attributes. To work with the primary key finder:
Execute the resource describe and locate the finders
attribute in the collection element. The name
attribute identifies the finder as PrimaryKey
. Also locate the name of the primary key attributes under attributes
.
Execute a GET with the query parameter finder
and pass the primary key attributes using the finder name PrimaryKey
.
For example, the Employees resources describe returns the following:
"collection" : { "rangeSize" : 24, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : false "precision" : 4, } ]
The following sample fetches the Employees
collection specified by the finder PrimaryKey
where the EmployeeId
attribute value 101
is passed.
Note: To filter the collection by a non-primary key attribute, see Filtering a Resource Collection with a Row Finder.
Request
URL
http://server/demo/rest/11.1/Employees?finder=PrimaryKey;EmployeeId=101
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "items" : [ { "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" } ] } ], "count" : 1, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "Employees", "kind" : "collection" } ] }
The ADF REST runtime supports fetching a resource collection using a GET method using query parameters.
The resource collection may be queried using expressions that differ in syntax depending on the ADF REST framework version that has been registered for the ADF REST service client. For details about the ADF REST framework versions, see What You May Need to Know About Versioning the ADF REST Runtime Framework.
The following samples are based on two different versions of the Departments
resource. The URL sample showing resource 11.0
reflects the query-by-example query parameter syntax supported only by version 1 of the ADF REST framework. While the URL sample showing resource 11.1
, reflects the rowmatch query parameter syntax supported in ADF REST framework version 2 (and later). In both framework scenarios, the samples fetch fields of the Departments
resource collection.
Note:
For a REST web service request, non-ASCII characters that appear in a query parameter value should be encoded. For example, the +
character in a timestamp value must be encoded as %2B
. Additionally, by default, resource and resource items names used in query parameter operations are case sensitive. If case insensitive filtering is desired, you may set the flag restV1QueryCaseSensitive
in the adf-config.xml
file to false
. The default value of the flag is true
which implies case sensitive filtering.
ADF REST Framework Version 2 (and later)
Starting with version 2 of the ADF REST framework, service clients may use an advanced query syntax, also known as rowmatch expressions, to fetch resources. For a complete description of the query syntax available in version 2 (and later), What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2.
The following sample fetches departments with names that begin with SA
(for example, SALES) or have a Location
of BOSTON
.
The following sample fetches all departments with at least one employee whose salary is equal to 10000. This is an example of fetching a parent object (Departments
) and filtering it by a child object attribute (Employees.Salary
).
Request Example 1 Made With Framework Version 2
URL
http://server/demo/rest/11.2/Departments?q=Employees.Salary = 10000
HTTP Method
GET
Content-Type
none
Payload
none
Response Example 1 From Framework Version 2
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload
{ "items" : [ { "DepartmentId" : 70, "DepartmentName" : "Public Relations", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments/70", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2/Departments/70", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.2/Departments/70/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 80, "DepartmentName" : "Sales", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments/820", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2/Departments/80", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.2/Departments/80/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments", "name" : "Departments", "kind" : "collection" } ] }
The following sample fetches all departments with the numeric ID of 10
or a department name that begins with the letter "H".
Request Example 2 Made With Framework Version 2
URL
http://server/demo/rest/11.1/Departments?q=DepartmentId = 10 or DepartmentName like 'H*'
HTTP Method
GET
Content-Type
none
Payload
none
Response Example 2 From Framework Version 2
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.2/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.2/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2/Departments", "name" : "Departments", "kind" : "collection" } ] }
ADF REST Framework Version 1
Version 1 of the ADF REST framework supports a query-by-example syntax. No application configuration changes are required to use this syntax that is supported only in versions 1. For a description of the query syntax available in version 1 of the ADF REST framework, see GET Method Operations.
The following sample fetches departments assigned a DepartmentId
value less than 30
.
Note:
In version 1 of the ADF REST framework, when you create a query with a string matching filter parameter and the string to match contains a query syntax reserved word (such as AND or OR), then the quoted string must be delimited by a space character to separate it from other parameters in the query expression. For example, the following query attempts to filter on the quoted string ‘Accounting and Finance’
. Since the string contains the reserved word AND, the string matching filter parameter requires a space before and after the single quotes to be viable in version 1.
?q=DepartmentName= 'Accounting and Finance' &fields=DepartmentName,Location
Note that starting in framework version 2, the use of a space character is no longer required to delimit a string matching filter that contains a reserved word.
Request Made With Framework Version 1
URL
http://server/demo/rest/11.0/Departments?q=DepartmentId<30
HTTP Method
GET
Content-Type
none
Payload
none
Response From Framework Version 1
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
The ADF REST runtime supports fetching an item of the resource collection using a GET method.
The following sample fetches version 11.0
of all fields of an instance of the Departments
resource collection.
Request
URL
http://server/demo/rest/11.0/Departments/50
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
The ADF REST runtime supports retrieving nested resources using a GET method.
The payload structure of nested child resource differs depending on the ADF REST framework version that has been registered for the ADF REST service client. For details about the ADF REST framework versions, see What You May Need to Know About Versioning the ADF REST Runtime Framework.
The following samples are based on two different versions of the Employees
resource. The URL samples showing resource 11.0
reflect a response payload structure supported by ADF REST framework versions 1 and 2. While the URL samples showing resource 11.1
, reflect the response payload structure supported in ADF REST framework version 3 (and later). In both framework scenarios, the samples fetch the Employees
resource as a child of the Departments
resource.
Note that the name used to identify the nested resource is determined at design time when the resource is created in the ADF Business Components model project. The default name for nested resources created in the model project is the destination view instance of the nested resource's defining view link accessor (such as EmployeesView1
for the view link DeptToEmpFkLink
). For this reason, it is a best practice for ADF REST resource developers to rename the resource to something more suitable as a URL parameter. In the following examples, the resource name was changed to Employees
to follow the naming convention for the parent resource name Departments
.
ADF REST Framework Version 3 (and later)
Starting with version 3 of the ADF REST framework, the ADF REST runtime returns a nested child resource in the response payload as a resource collection, instead of as an array of resource items. This functionality, available in framework version 3 (and later), allows service clients to make a request for additional records after determining how many items were left unfetched in the initial request. The attributes hasMore
and count
on the child resource indicate whether more items may be returned from the resource collection. For details about using the pagination attributes from the response payload when you opt into ADF REST framework version 3, see Paging a Resource Collection.
The following sample illustrates functionality for ADF REST framework version 3 (and later). The response payload represents the nested child resource as a resource collection, where the collection object includes the hasMore
and count
attributes. A link is provided should it be necessary to query the child resource for additional resource items. In this sample, items of the Employees
child resource are fetched with a count
of 3
in the payload. The response payload shows the hasMore
attribute is false
, suggesting that no items remain unfetched.
Request Made With Framework Version 3
URL
http://server/demo/rest/11.1/Departments/50?expand=Employees
HTTP Method
GET
Content-Type
none
Payload
none
Response From Framework Version 3
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "DepartmentId" : 50, "DepartmentName" : "Shipping", "Employees" : { "items" : [ { "EmployeeId" : 120, "FirstName" : "Matthew", "LastName" : "Weiss", "Email" : "MWEISS", "JobId" : "ST_MAN", "DepartmentId" : 50, "Salary" : 8000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.1/Departments/50", "name" : "Departments", "kind" : "item" } ] }, { "EmployeeId" : 121, "FirstName" : "Adam", "LastName" : "Fripp", "Email" : "AFRIPP", "JobId" : "ST_MAN", "DepartmentId" : 50, "Salary" : 8200, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees/121", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees/121", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.1/Departments/50", "name" : "Departments", "kind" : "item" } ] }, { ... } ] } ], "count" : 3, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Departments/50", "name" : "Departments", "kind" : "item" } ] }
ADF REST Framework Version 1 or Version 2
Version 1 and version 2 of the ADF REST framework return the nested child resource expanded in the response payload as an array of resource items. If the resource collection being fetched is large, you may have to make several requests since the array of resource items has a limit.
The following samples illustrate functionality for ADF REST framework version 1 and version 2.
The first request sample (URL 1) retrieves a single child resource item identified by employee 120
. The URL parameter child
identifies the relationship of the requested resource Employees
.
The second request (URL 2) shows the use of the query parameter expand
to ensure that all nested Employees
resource items will be returned with Departments
resource collection 50
.
The third request (URL 3) shows the use of accessor dot notation (for example, Employees.JobHistory
) in combination with the query parameter expand
to ensure that all nested JobHistory
resource items will be returned with the Employees
resource items for the Departments
resource collection 80
.
Request Made With Framework Version 1 or Version 2
URL 1
http://server/demo/rest/11.0/Departments/50/child/Employees/120
URL 2
http://server/demo/rest/11.0/Departments/50?expand=Employees
URL 3
http://server/demo/rest/11.0/Departments/80?expand=Employees.JobHistory&onlyData=true
HTTP Method
GET
Content-Type
none
Payload
none
Response From Framework Version 1 or Version 2
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload 1
{ "EmployeeId" : 120, "FirstName" : "Matthew", "LastName" : "Weiss", "Email" : "MWEISS", "JobId" : "ST_MAN", "DepartmentId" : 50, "Salary" : 8000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" } ] }
Payload 2
{
"DepartmentId" : 50,
"DepartmentName" : "Shipping",
"Employees" : [ {
"EmployeeId" : 120,
"FirstName" : "Matthew",
"LastName" : "Weiss",
"Email" : "MWEISS",
"JobId" : "ST_MAN",
"DepartmentId" : 50,
"Salary" : 8000,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/120",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/120",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "parent",
"href" : "http://server/demo/rest/11.0/Departments/50",
"name" : "Departments",
"kind" : "item"
} ]
}, {
"EmployeeId" : 121,
"FirstName" : "Adam",
"LastName" : "Fripp",
"Email" : "AFRIPP",
"JobId" : "ST_MAN",
"DepartmentId" : 50,
"Salary" : 8200,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/121",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/50/child/Employees/121",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "parent",
"href" : "http://server/demo/rest/11.0/Departments/50",
"name" : "Departments",
"kind" : "item"
} ]
}, {
...
} ]
} ],
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/50",
"name" : "Departments",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/50",
"name" : "Departments",
"kind" : "item"
} ]
}
Payload 3
{ "DepartmentId" : 80, "DepartmentName" : "Sales", "RelState" : null, "Employees" : [ ... { "EmployeeId" : 176, "FirstName" : "Jonathon", "LastName" : "Taylor", "Email" : "JTAYLOR", "JobId" : "SA_REP", "DepartmentId" : 80, "Salary" : 8600, "CommissionPct" : 0.2, "JobHistory" : [ { "EmployeeId" : 176, "StartDate" : "2011-03-24", "EndDate" : "2012-12-31", "JobId" : "SA_REP", "DepartmentId" : 80 }, { "EmployeeId" : 176, "StartDate" : "2013-01-01", "EndDate" : "2015-03-31", "JobId" : "SA_MAN", "DepartmentId" : 80 } ] }, ... ] }
The ADF REST runtime supports sorting the fetched resource collection using a GET method.
Sorting a resource collection is performed using the orderBy query string parameter in combination with one or more attribute names. The following optional sort order flags may be associated with each attribute:
asc sorts in ascending order. (Default)
desc sorts in descending order.
The orderBy query string parameter format is:
<orderBy_attribute1_name>:<(asc/desc)>, <orderBy_attribute2_name>:<(asc/desc)>
Example: attribute1:asc,attribute2
The following sample (URL1) fetches the Departments
collection sorted by the DepartmentName
attribute. The second sample (URL2) fetches the child Employees
collection sorted by the salary
attribute. Since the sort order flag is not specified for either request sample, the response is ascending order.
Request
URL 1
http://server/demo/rest/11.0/Departments?orderBy=DepartmentName
URL 2
http://server/demo/rest/11.0/Departments/50/child/Employees?orderBy=Salary
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload 1
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 5, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
Payload 2
{ "items" : [ { "EmployeeId" : 132, "FirstName" : "TJ", "LastName" : "Olson", "Email" : "TJOLSON", "JobId" : "ST_CLERK", "DepartmentId" : 50, "Salary" : 2100, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/132", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/132", "name" : "Employees", "kind" : "item" } ] }, { "EmployeeId" : 136, "FirstName" : "Hazel", "LastName" : "Philtanker", "Email" : "HPHILTAN", "JobId" : "ST_CLERK", "DepartmentId" : 50, "Salary" : 3100, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/136", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/136", "name" : "Employees", "kind" : "item" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees", "name" : "Employees", "kind" : "collection" } ] }
The ADF REST runtime supports the following creation use cases:
Creating a resource item in collection.
Creating a child resource item.
The ADF REST runtime supports creating resource items on an existing resource collection using a POST method.
Before making a request with the POST method, determine whether the resource item is defined by an LOV-enabled attribute. If an LOV-enabled attribute is present and that attribute is defined as mandatory, you must first access the LOV resource on the resource collection to display the selection list to the end user. For details about how to access an LOV resource, see Retrieving LOV-Enabled Attribute Values When Creating a Resource Item.
The following sample creates a new Departments
resource collection with a single item.
Request
URL
http://server/demo/rest/11.0/Departments
HTTP Method
POST
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "DepartmentId" : 15, "DepartmentName" : "NewDept" }
Response
HTTP Code
201
Content-Type
application/vnd.oracle.adf.resourceitem+json
Location
http://server/demo/rest/Departments/15
Payload
{ "DepartmentId" : 15, "DepartmentName" : "NewDept", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
The ADF REST runtime supports creating ADF REST child resource items in one roundtrip using a POST method. Create will only succeed when both the parent and child do not exist.
The following samples create nested resource items. The first request sample (URL1) creates a child resource item identified by employee 999
in an existing Departments
resource. The second request (URL2) creates the parent and child resources.
Request
URL 1
http://server/demo/rest/11.0/Departments/15/child/Employees
URL 2
http://server/demo/rest/11.0/Departments
HTTP Method
POST
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload 1
{ "EmployeeId": 999, "FirstName": "New", "LastName": "Guy", "Email": "NGUY", "JobId": "SA_REP", "DepartmentId": 15, "Salary": 9999 }
Payload 2
{ "DepartmentId": 17, "DepartmentName": "NewerDept", "Employees": [ { "EmployeeId": 99999, "FirstName": "Newer", "LastName": "Guy", "Email": "NRGUY", "JobId": "SA_MAN", "DepartmentId": 17, "Salary": 10001 } ] }
Response
HTTP Code
201
Content-Type
application/vnd.oracle.adf.resourceitem+json
Location
http://server/demo/rest/11.0/Departments/15/child/Employees/999
Payload 1
{ "EmployeeId" : 999, "FirstName" : "New", "LastName" : "Guy", "Email" : "NGUY", "JobId" : "SA_REP", "DepartmentId" : 15, "Salary" : 9999, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees/999", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees/999", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees/999/lov/JobsView1", "name" : "JobsView1", "kind" : "collection" } ] }
Location
http://server/demo/rest/11.0/Departments/17/child/Employees/99999
Payload 2
{ "DepartmentId" : 17, "DepartmentName" : "NewerDept", "Employees" : [ { "EmployeeId" : 99999, "FirstName" : "Newer", "LastName" : "Guy", "Email" : "NRGUY", "JobId" : "SA_MAN", "DepartmentId" : 17, "Salary" : 10001, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/17/child/Employees/99999", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/17/child/Employees/99999", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/11.0/Departments/17", "name" : "Departments", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Departments/17/child/Employees/99999/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/17", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/17", "name" : "Departments", "kind" : "item" } ] }
The ADF REST runtime supports updating resource items using a PATCH method. Update will only succeed when the row already exists.
The following sample updates Departments
item 15
, where DepartmentName
is changed in the request payload.
Request
URL
http://server/demo/rest/11.0/Departments/15
HTTP Method
PATCH
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "DepartmentId" : 15, "DepartmentName" : "UpdatedDeptName" }
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "DepartmentId" : 15, "DepartmentName" : "UpdatedDeptName", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
The ADF REST runtime supports deleting resource items using a DELETE method. The framework does not currently support deleting a resource collection.
The following sample (URL1) deletes employee ID 99999
of the Employees
resource collection as a child of the Departments
resource item 17
. The second request URL deletes the Departments
resource item 17
.
Request
URL 1
http://server/demo/rest/11.0/Departments/17/child/Employees/99999
URL 2
http://server/demo/rest/11.0/Departments/17
HTTP Method
DELETE
Content-Type
none
Payload
none
Response
HTTP Code
204
Content-Type
none
Payload
none
The ADF REST runtime supports generating an entity tag (ETag) in the response header when the requested resource has data consistency check enabled. Data consistency checking is enabled by the ADF Business Components developer who must configure a change-indicator attribute on the entity object backing the resource.
When entity change indicators are configured on the entity object backing the resource, the ADF REST runtime will assign a unique value to indicate the state of each resource on the server side. At runtime, when the row underlying the server side resource changes, Oracle ADF assigns a new state value to the ETag. The following header shows the ETag returned with a request to retrieve a Departments
resource item.
HTTP/1.1 200 OK Cache-Control: no-cache, no-store, must-revalidate Location: Content-Length: 1069 Content-Type: application/json ETag: "ACED00057372037200136261636C6520136261636C65237200136261636C652" Content-Encoding: Link: <http://server/demo/rest/11.0/Departments/10>;rel="self";kind="item";name="Departments"
Note:
Note that the ETag and data consistency checking are not automatically enabled for REST resources. To support generating ETag values, the ADF Business Components developer must configure a change-indicator enabled attribute on the entity object backing the resource to be checked. For details about configuring change indicator attributes for entity objects, see How to Protect Against Losing Simultaneously Updated Data.
The service client can use the ETag value returned in the header response of each resource item to create subsequent requests that contain precondition headers (If-Match
/If-None-Match
). Based on the specified ETag and the precondition, the server will evaluate the current resource state and match against the provided ETag. If the precondition is satisfied, the requested operation is executed; otherwise, a 412
error is returned. The error payload will contain the current resource in the server side and the header will also reflect the current ETag value.
To support testing ETag values, the ADF REST framework provides the following precondition header fields. Usage of these precondition fields forces the framework to compare a supplied ETag value against the ETag values of previously requested items.
Verify that the client is providing a state (obtained from a previous resource item response) that matches the current state on the server:
If-Match: "<ETag value from resource item response>"
Verify that the client is providing a state (obtained from a previous resource item response) that does not match the current state on the server.
If-None-Match: "<ETag value from resource item response>"
The following are typical use cases when checking for data consistency:
Check that the resource item matches the server side resource state before updating
Retrieve the resource item using the server side resource state when none of the requested items match any previously requested items
While these use cases involve GET and PATCH methods, the precondition header and ETag value can be used to check that any HTTP method operation will be applied to the current state of the resource.
When retrieving a resource collection, an additional custom property changeIndicator
will appear in the response payload of resources with data consistency enabled. This property contains the current ETag value of each resource item in the requested collection. The following sample illustrates the changeIndicator
property in the links
section of a Departments
resource collection. The presence of ETag values in the resource collection payload is a convenience for the service client that can reduce the number of requests to obtain the ETag from individual resource items.
Note also the presence of the RelState
attribute in the response. This is the name of the change-indicator attribute that the ADF Business Components developer configured on the entity object to support data consistency checks. The value of the attribute reflects the number of times the state has been updated.
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "RelState" : 1, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C69737 47881D21D99C7619D03000149000473697A65787000000001770400000001737200186F721 636C652E6A626F2E646F6D61696E2E4E7564A362286F0200015B0004646174617400025B45 27870757200025B42ACF317F8060854E00200007870" } "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item", }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "ACED0005737200136A6176612E7574696C2E149000473697A6578 70000000017704000000017372001B6F7261636C652E6A626F2E646F60000C78" } }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection", } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200186F7261636C652E6A626F2E646F6D61696E2E4E756D626572A5B1371914E0BFDA0200014900096D48617368436F6465787200116F7261636C652E73716C2E4E554D424552E90466EE632BE1D5020000787200106F7261636C652E73716C2E446174756D4078F514A362286F0200015B0004646174617400025B427870757200025B42ACF317F8060854E0020000787000000002C10A0000000078" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { ... } ] } ], "count" : 5, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
The ADF REST runtime support checking for data consistency when using a PATCH method to update resource items backed by an ADF Business Components entity object with a change-indicator attribute enabled.
To check for data consistency using the ETag header and conditional header fields:
Obtain the ETag value from the header of a GET request for the resource item:
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Location:
Content-Length: 861
Content-Type: application/json
ETag: "responseETag123"
Content-Encoding:
Link: <http://server/demo/rest/11.0/Departments/10>;rel="self";kind="item";name="Departments"
Set-Cookie: JSESSIONID=jXvsJ1GpdkFJV5Jh0yk7D72vPZ42t8tLYDg74NRKFQzXdnsjG9vv!1113104013; path=/; HttpOnly
X-ORACLE-DMS-ECID: 51f1ff4535af720c:-7e156247:148ec9eeb3b:-8000-00000000000001ad
X-Powered-By: Servlet/2.5 JSP/2.1
{
"DepartmentId" : 10,
"DepartmentName" : "Administration",
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "responseETag123"
}
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item"
}, {
"rel" : "child",
"href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
"name" : "Employees",
"kind" : "collection"
} ]
}
Make the PATCH request for the resource item and check for data consistency by supplying the following conditional header field:
If-Match: "
<ETag value from resource item response>
"
to verify that the state of a requested resource item is current with the previous resource item response.
The following sample updates the DepartmentName
field of the Departments 10
resource item when the If-Match
precondition test is satisfied. In the first request (Request 1), the ETag value responseETag123
is identical to the ETag of the current Departments
10
resource item on the server side, indicating that the state of the resource item is consistent with the server side. Consequently, the update to DepartmentName
is allowed.
In the subsequent request (Request 2), however, the ETag supplied in the If-Match
precondition is unchanged and no longer matches the new ETag value the server has for the Departments
10
resource item. As a consequence of the stale ETag value used in the second request, the update fails with an HTTP code 412
, indicating the precondition test failed, and the current ETag value responseETag567
is returned in the response header.
Request 1
URL 1
http://server/demo/rest/11.0/Departments/10
HTTP Method
PATCH
Precondition 1
If-Match: "responseETag123"
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload 1
{ "DepartmentName" : "FirstAttempt_NewDepartmentName" }
Response 1
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
ETag
responseETag567
Payload 1
{
"DepartmentId" : 10,
"DepartmentName" : "FirstAttempt_NewDepartmentName",
"RelState" : null,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "responseETag567"
}
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item"
}, {
"rel" : "child",
"href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
"name" : "Employees",
"kind" : "collection"
} ]
}
Request 2
URL 2
http://server/demo/rest/11.0/Departments/10
HTTP Method
PATCH
Precondition 2
If-Match: "staleETag789"
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload 2
{ "DepartmentName" : "SecondAttempt_NewDepartmentName" }
Response 2
HTTP Code
412
(Precondition failed)
Content-Type
application/vnd.oracle.adf.resourceitem+json
ETag
responseETag567
Payload 2
{
"DepartmentId" : 10,
"DepartmentName" : "FirstAttempt_NewDepartmentName",
"RelState" : null,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "responseETag567"
}
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item"
}, {
"rel" : "child",
"href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
"name" : "Employees",
"kind" : "collection"
} ]
}
The ADF REST runtime supports checking for data consistency when using a GET method to retrieve resource items backed by an ADF Business Components entity object with a change-indicator attribute enabled.
To check for data consistency using the ETag header and conditional header fields:
Obtain the ETag value from the header of a GET request for the resource item:
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Location:
Content-Length: 861
Content-Type: application/json
ETag: "responseETag123"
Content-Encoding:
Link: <http://server/demo/rest/11.0/Departments/10>;rel="self";kind="item";name="Departments"
Set-Cookie: JSESSIONID=jXvsJ1GpdkFJV5Jh0yk7D72vPZ42t8tLYDg74NRKFQzXdnsjG9vv!1113104013; path=/; HttpOnly
X-ORACLE-DMS-ECID: 51f1ff4535af720c:-7e156247:148ec9eeb3b:-8000-00000000000001ad
X-Powered-By: Servlet/2.5 JSP/2.1
{
"DepartmentId" : 10,
"DepartmentName" : "Administration",
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "ACED0005737200136A6176612E7574696C2E4"
}
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item"
}, {
"rel" : "child",
"href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
"name" : "Employees",
"kind" : "collection"
} ]
}
Make the GET request for the resource item and check for data consistency by supplying the following conditional header field:
If-None-Match: "
<ETag value from resource item response>
"
to verify that the state of none of the previously requested resource items is current with the resource item request.
The following sample retrieves the Departments 10
resource item when the If-None-Match
precondition test is satisfied. In the first request (Request 1), the ETag value responseETag123
matches the ETag of the previously requested Departments
10
resource item on the server side, indicating that the state of the resource item is consistent with the server side. Consequently, the precondition fails and there is no need to return a newer Departments 10
resource item. The request returns with an HTTP code 304
, indicating the state on the server has not been modified.
In the subsequent request (Request 2), however, the ETag unmatchedETagXYZ
supplied in the If-None-Match
precondition does not exist on the server. As a consequence, the precondition succeeds and the Departments
10
resource item is retrieved. The request returns an HTTP code 200
, indicating the state had changed, and the current (unchanged) ETag value responseETag123
is returned in the response header.
Request 1
URL 1
http://server/demo/rest/11.0/Departments/10
HTTP Method
GET
Precondition 1
If-None-Match: "responseETag123"
Content-Type
none
Payload
none
Response 1
HTTP Code
304
state not modified
Content-Type
none
Payload 1
none
Request 2
URL 2
http://server/demo/rest/11.0/Departments/10
HTTP Method
GET
Precondition 2
If-None-Match: "unmatchedETagXYZ"
Content-Type
none
Payload
none
Response 2
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
ETag
responseETag123
Payload 2
{
"DepartmentId" : 10,
"DepartmentName" : "Administration",
"RelState" : null,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "responseETag123"
}
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Departments/10",
"name" : "Departments",
"kind" : "item"
}, {
"rel" : "child",
"href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
"name" : "Employees",
"kind" : "collection"
} ]
}
The ADF REST runtime supports content streaming for BLOB or CLOB attributes.
LOB attributes may be handled in the following ways.
Linked to as custom content that is not contained in the payload itself.
This is the default for BLOB and CLOB attributes and specified in the response payload using the enclosure
link type to point to a resource that cannot be represented with the supported payload types (such as image/png
).
Encoded into Base64
string format and contained in the request payload itself.
Currently, advanced features (like support for Chunked encoding) are not supported by the ADF REST runtime. Developers working on an enterprise architecture, may wish to investigate the use of specialized content management systems (such as Oracle WebCenter Content).
Instead of showing the LOB attribute in the attribute
section, the response payload always contains an enclosure
link to the content. The following describe for an Employees
resource item defines the BLOB attribute Picture
with a default requestType
of application/octet-stream
. The enclosure
link for the resource item appears in the items
section. The actions
section identifies the operations that may be used to manipulate the content.
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { ... }, { "name" : "Picture", "type" : "attachment", "updatable" : true, "mandatory" : false, "queryable" : false, "actions" : [ { "name" : "delete", "method" : "DELETE" }, { "name" : "get", "method" : "GET", "responseType" : [ "application/octet-stream" ] } ] } ], "item" : { "links" : [ { ... }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Employees/101/enclosure/Picture", "name" : "Picture", "kind" : "other" } ], "actions" : [ { } ] }, "links" : [ { ... } ] } }
The attribute content type of the resource item can be assigned by the ADF REST resource developer by configuring the contentType
property as a custom property of the LOB-type attribute. For example, when working with PNG image files, the following content type can assigned in advance:
Custom Property: contentType
Value: image/png
In some use cases the attribute value itself is a link to some external content. When an attribute is configured this way, it is not only shown in the resource item payload but a link that points to the external content is also created. In the resource description, only the GET action will be available for the external link. You can modify the URL contained in the attribute value by making a request with an update on the resource item.
An attribute can be configured by the ADF REST resource developer to generate a link by adding the following attribute:
Name: inputHandler
Value: oracle.adf.internal.model.rest.core.binding.inputHandler.LinkInputHandler
The ADF REST runtime supports streaming content that cannot be contained in the payload of a resource item by using a link to the content. Supported methods on the linked content include GET and DELETE. Note that creating LOB content at the same time that you create a resource item (using a POST method) requires encoding the content as base64
. A sample of how to embed content using base64
can be found in Replacing LOB Content Using Base64.
To stream content from a link:
Retrieve the resource item and locate the enclosure
link for the desired attribute. The item
section defines the available links for the attribute.
Alternatively, you can execute the resource describe to identify the enclosure link generated for resource items. In general, the resource describe contains other useful information not returned in the GET response payload, including the expected response type (image/png
, for example) and supported actions for the attribute.
Execute an HTTP operation (GET or DELETE) using the link to the LOB content.
The following resource item for Employees
101
shows the enclosure
link for the Picture
attribute in the links
section.
{ "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/11.0/Employees/101/enclosure/Picture", "name" : "Picture", "kind" : "other" } ] }
For example, the following sample streams the PNG image associated with employee 101.
Note that by default the request type is application/octet-stream
to support a variety of media types. If the ADF REST resource developer defined the custom property contentType
, the specified request type appears in the resource item describe.
Request
URL
http://server/demo/rest/11.0/Employees/101/enclosure/Picture
HTTP Method
GET
Content Type
none
Payload
none
Response
HTTP Code
200
Content-Type
image/png
Payload
content streamed
The ADF REST runtime allows creating and updating LOB content using a JSON payload when the content is represented in base64
string format.
For example, the following sample replaces a PNG image for employee 101
. In this use case, the Picture
attribute must be represented in the request payload as String encoded in base64
. Because resource item 101
already exists and only the Picture
attribute is being manipulated, no other attributes need to be specified.
Note that the response payload contains the enclosure
link to the Picture
attribute.
Request
URL
http://server/demo/rest/11.0/Employees/101
HTTP Method
PATCH
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "Picture" : "/9j/4AAQSkZJRgABAAEAYABgAAD//..." }
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{
"EmployeeId" : 101,
"FirstName" : "Neena",
"LastName" : "Smith",
"Email" : "NSMITH",
"JobId" : "AD_VP",
"DepartmentId" : 90,
"Salary" : 2000,
"links" : [ {
"rel" : "lov",
"href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV",
"name" : "JobsLOV",
"kind" : "collection"
}, {
"rel" : "self",
"href" : "http://server/demo/rest/11.0/Employees/101",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/11.0/Employees/101",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "enclosure",
"href" : "http://server/demo/rest/11.0/Employees/101/enclosure/Picture",
"name" : "Picture",
"kind" : "other"
} ]
}
The ADF REST runtime supports LOV-enabled attributes use cases:
Retrieving LOV attribute values in the context of an existing resource item.
Refer to this use case when you need to allow users to update an existing resource item and the resource item defines an LOV-enabled attribute.
Retrieving LOV attribute values when no context for an existing resource item exists.
Refer to this use case when you need to create a resource item and that resource item defines an LOV-enabled attribute.
The ADF REST runtime supports retrieving the values from LOV-enabled attributes using a GET method on an existing resource item.
An existing resource item for an LOV-enabled attribute nests an LOV child resource that you can use to obtain the list of values that is appropriate based on the context of the containing resource item.
When you create a new resource item and need to retrieve LOV values, you access an LOV resource that is not nested inside the resource collection. For details about accessing a non-nested LOV resource, see Retrieving LOV-Enabled Attribute Values When Creating a Resource Item.
To work with LOV-enabled attributes on existing resource items:
Execute the resource describe and locate the following details about the LOV:
Under the lov
description of a resource attribute, locate the childRef
property to identify the child resource collection that contains the LOV choices.
The lov
description contains the view object attribute mapping from the resource item to the LOV child resource collection. The attribute mapping contains one or more source attributes from the child resource whose values will be copied to the resource item when an LOV value is selected. An LOV selection could derive more values in the resource item besides the attribute displaying the LOV. In such cases, the attribute mapping will identify it as derived = true
. Finally, the lov
description identifies which attributes from the child resource collection could be used for displaying to end users if the results are bound to a user interface.
Then, look for the resource item links
element and locate the link with a rel
of lov
and the href
that identifies the corresponding LOV child resource (as specified in the resource item childRef
property).
Tip: The resource describe displays the LOV child resource as a template that is completed by supplying a specific resource item name from the resource collection. You may execute a GET to retrieve the resource collection and locate the working link for the LOV child resource that corresponds to the specific resource item.
Execute a GET using the LOV link and, optionally, use additional filtering to narrow down the LOV results or to exclude not needed attributes from the payload. You should always fetch the display attributes listed in the lov
description. The display attribute is the attribute value that allows the end user to make an LOV value selection from a list of values that they would recognize (such as the list of job titles). The LOV definition ensures that the correct source attribute is used to update the resource item when the LOV selection is applied.
For example, the Employees
resource collection describe returns the following:
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobId", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ] } ... "item" : { "links" : [ { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Employees/{id}/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" }, { ...
The following sample fetches the values for the LOV display attribute JobTitle
from the JobsLOV
resource collection. The query parameters onlyData
and fields
ensure the representation is filtered to contain only data in the response payload, where President
and Administration Assistant
are examples of the values of the display attribute JobTitle
.
Request
URL
http://server/demo/rest/11.0/Employees/101/lov/JobsLOV?onlyData=true&fields=JobTitle
HTTP Method
GET
Content-Type
none
Payload
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload
{ "items" : [ { "JobTitle" : "President" }, { "JobTitle" : "Administration Assistant" }, { "JobTitle" : "Finance Manager" }, { "JobTitle" : "Accountant" }, { "JobTitle" : "Accounting Manager" }, { "JobTitle" : "Public Accountant" } ], "count" : 6, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] }
The ADF REST runtime supports retrieving the values from LOV-enabled attributes using a GET method when it is necessary to create a new resource item that does not exist in the resource collection.
For an already existing resource item, use the resource item link to access the LOV child resource that has been defined for the particular item. For details about accessing the LOV child resource, see Retrieving LOV-Enabled Attribute Values for Existing Resource Items.
To work with LOV-enabled attributes when creating a resource item:
Execute the resource describe and locate the following details about the LOV:
Under the lov
description of an attribute, locate the lovResourcePath
property to identify the LOV resource that contains the LOV choices.
The lov
description contains the attribute mapping from the resource item to the LOV resource collection. The attribute mapping contains one or more source attributes from the LOV resource whose values will be copied to the resource item when an LOV value is selected. An LOV selection could derive more values in the resource item besides the attribute displaying the LOV. In such cases, the attribute mapping will identify it as derived = true
. Finally, the lov
description identifies which attributes from the LOV resource collection could be used for displaying to end users if the results are bound to a user interface.
Then, look for the resource collection describe links
element and locate the link with a rel
of lov
and the href
that identifies the LOV resource (as specified in the lovResourcePath
property).
Note the lovResourcePath
is an array that may specify more than one LOV resource. The array supports the use case of dependent LOV-enabled attributes (also called cascading LOVs). For example, the array "lovResourcePath" : [ "Countries", "States" ]
identifies LOV resources Countries
and States
, where the LOV list to display the states is dependent on the LOV selection for countries. To get the values to display for the dependent LOV attribute, you use a child link from the parent LOV resource collection as follows:
Execute a GET using the LOV resource link (where rel: lov
and name: Countries
).
The end user selects a resource item from the LOV resource collection (for example, United States
).
Execute a GET using the child link (rel: child
and name: States
) in the selected resource item. This will retrieve a resource collection with the list of values (states) based on the parent LOV resource (countries).
Execute a GET using the LOV resource link and, optionally, use additional filtering to narrow down the LOV results or to exclude not needed attributes from the payload. You should always fetch the display attributes listed in the lov
description. The display attribute is the attribute value that allows the end user to make an LOV value selection from a list of values that they would recognize (such as the list of job titles).
With the cached LOV attribute values from the LOV resource, it is then possible to display the LOV display attribute in the client user interface where the end user is expected to enter values to create a new resource item. When enters the desired values, chooses a value from the displayed LOV for the LOV-enabled attribute, and then clicks Submit, the client can execute the create request. The ADF Business Components view object attribute's LOV definition ensures that the correct source attribute is used to update the resource item when the LOV selection is applied. For details about submitting a POST request with the payload that creates a new resource item, see Creating a Resource Item in Collection.
For example, the Employees
resource collection describe returns the following:
{ "Resources" : { "Employees" : { "discrColumnType" : false, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 25 }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 10, "controlType" : "choice", "maxLength" : "10", "lov" : { "childRef" : "JobsLOV", "attributeMap" : [ { "source" : "JobId", "target" : "JobId" } ], "displayAttributes" : [ "JobTitle" ], "lovResourcePath" : [ "Jobs" ] } ... }, "links" : [ { ... "rel" : "lov", "href" : "http://server/demo/rest/11.0/Jobs", "name" : "Jobs", "kind" : "collection" }, { ...
The following sample fetches the values for the LOV display attribute JobTitle
from the Jobs
resource collection. The query parameters onlyData
and fields
ensure the representation is filtered to contain only data in the response payload, where President
and Administration Assistant
are examples of the values of the display attribute JobTitle
.
Request
URL
http://server/demo/rest/11.0/Jobs?onlyData=true&fields=JobTitle
HTTP Method
GET
Content-Type
none
Payload
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload
{ "items" : [ { "JobTitle" : "President" }, { "JobTitle" : "Administration Assistant" }, { "JobTitle" : "Finance Manager" }, { "JobTitle" : "Accountant" }, { "JobTitle" : "Accounting Manager" }, { "JobTitle" : "Public Accountant" } ], "count" : 6, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Jobs", "name" : "Jobs", "kind" : "collection" } ] }
Service clients may need to pass a different payload format to utilize a new feature or enhancement, such as the advanced query capabilities offered in version 2 of the ADF REST runtime framework. A framework version refers to a specific version of the ADF REST framework available starting in a particular Oracle JDeveloper release.
Being able to specify a framework version to process requests, allows clients to opt into those features when they are ready.
The ADF REST runtime supports the following use cases for executing requests according to specific ADF REST framework versions:
Ability for service clients to specify a framework version that affects the processing of the payload.
Ability for service clients to indicate the default framework version (as configured by the server) to be used.
Ability for ADF REST resource developers to declare the default framework version for all URIs under a release version:
When a request does not specify a framework version, all payloads for URIs starting with /context/<release-version>/
will assume the default framework version as declared in the adf-config.xml
file.
When a request specifies a framework version, the specified framework version will be honored.
Service clients may pass the custom header REST-Framework-Version
on the REST resource request to specify the framework version to use to execute the request. The ADF REST framework version passed in the version header overrides the default framework declaration defined by the application in the adf-config.xml
file by the REST service developer.
When the service client passes no version header in the request, the ADF REST runtime uses the default, as defined in the adf-config.xml
file. When a default framework version is not defined and no version header is passed, then the base version (version 1) of the ADF REST framework is assumed.
The framework version declaration is made by ADF REST resource developers in the adf-config.xml
file for each application-specific resource version name. For example, the sample following shows resource versions 11.2
, 11.1
, and 11.0
with the framework versions 3
, 2
, and 1
declared.
<versions> <version name="11.2" displayName="11.2" restFrameworkVersion="2"/> <version name="11.1" displayName="11.1" lifecycle="deprecated" restFrameworkVersion="1"/> <version name="11.0" displayName="11.0" lifecycle="deprecated" restFrameworkVersion="1"/> </versions>
In the above example, when the request does not pass a framework version header, resources 11.0
and 11.1
will use the old payload format, while 11.2
will use the new payload format. This ensures, in cases where a framework version is not specified in the request, existing service clients which access resources for a particular release will not be affected when the ADF REST framework introduces a new payload format; yet new service clients which access the latest resources may pick up the new payload format.
For the root resource /context
, the default ADF REST framework version for the latest release will be used.
The service client may want to find out the default framework version for a particular release. To support this use case, ADF REST will return the default framework version in the resource version describe, as the following sample shows.
{ "items" : [ { "version" : "11.2", "isLatest" : true, "adf:extension" : { "defaultFrameworkVersion" : "2", }, "links" : [ ...
For details about the ADF REST framework functionality supported in each framework version, see What You May Need to Know About Versioning the ADF REST Runtime Framework.
The ADF REST runtime supports retrieving the version of the ADF REST framework associated with each application-specific release version name that the service end point defines using a GET method.
While the release versions named in the REST application are specific to the application’s REST resources, framework versions designate a change in functionality of the ADF REST framework and correspond to a particular JDeveloper release. To ensure the service endpoint exposes the desired level of functionality to service clients, REST resource developers may optionally assign a framework version to each REST resource release version name in the application’s adf-config.xml
file.
Note:
For details about the ADF REST framework functionality supported in each framework version, see What You May Need to Know About Versioning the ADF REST Runtime Framework.
To examine the framework version assigned to the release version names that the application defines:
Execute the service end point describe and locate the available release version names in the describe.
Locate the version
property to identify the release version.
Examine the associated defaultFrameworkVersion
property to understand the version of the ADF REST framework that will be used to execute requests for the specific release version.
For example, the describe for a service end point with two release versions returns the following objects, where each release version has been associated with a specific ADF REST framework version:
{ "items" : [ { "version" : "version_identifier_latest", "isLatest" : true, "adf:extension" : { "defaultFrameworkVersion" : "framework_identfier", }, "links" : [ { "rel" : "self", ... }, { "rel" : "canonical", ... }, { "rel" : "predecessor-version", ... }, { "rel" : "describe", ... } ] }, { "version" : "version_identifier_previous", "adf:extension" : { "defaultFrameworkVersion" : "framework_identfier", }, "links" : [ { "rel" : "self", ... }, { "rel" : "canonical", ... }, { "rel" : "successor-version", ... }, { "rel" : "describe", ... } ] } ], "links" : [ ... { "rel" : "current", ... } ] }
The following sample retrieves all available release versions defined in the resource catalog of the demo
application. In the sample, the three release versions are 11.0
, 11.1
, and 11.2
, where 11.2
is the current (or most recent) release version. In the sample, versions 11.0
and 11.1
are explicitly associated with ADF REST framework version 1
and release version 11.2
is associated with ADF REST framework version 2
. Note that a framework version refers to a specific version of the ADF REST framework, available starting in a particular Oracle JDeveloper release.
Request
URL
http://server/demo/rest
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.description+json
Payload
{ "items" : [ { "version" : "11.2", "isLatest" : true, "adf:extension" : { "defaultFrameworkVersion" : "2", }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.2", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.2", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/11.1", "name" : "predecessor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.2/describe", "name" : "describe", "kind" : "describe" } ] }, { "version" : "11.1", "adf:extension" : { "defaultFrameworkVersion" : "1", }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/11.0", "name" : "predecessor-version", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/11.2", "name" : "successor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.1/describe", "name" : "describe", "kind" : "describe" } ] }, { "version" : "11.0", "adf:extension" : { "defaultFrameworkVersion" : "1", }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0", "name" : "canonical", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/11.1", "name" : "successor-version", "kind" : "item" }, { "rel" : "describe", "href" : "http://server/demo/rest/11.0/describe", "name" : "describe", "kind" : "describe" } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest", "name" : "self", "kind" : "collection" }, { "rel" : "canonical", "href" : "http://server/demo/rest", "name" : "canonical", "kind" : "collection" }, { "rel" : "current", "href" : "http://server/demo/rest/11.2", "name" : "current", "kind" : "item" } ] }
The ADF REST runtime supports executing individual requests on the service endpoint using a custom header to affect the processing of the payload with the functionality specific to a particular ADF REST framework version. The framework version specified by the custom header overrides the default framework version declaration that may exist in the client application.
Note:
A framework version refers to a specific version of the ADF REST framework (corresponding to a particular Oracle JDeveloper release). For details about the ADF REST framework functionality supported in each framework version, see What You May Need to Know About Versioning the ADF REST Runtime Framework.
To ensure the service endpoint exposes the desired level of functionality to service clients, REST resource developers may optionally assign a default ADF REST framework version to each REST resource version named in the application’s adf-config.xml
file. However, the service client may override the default framework version and process individual requests using a specified framework version that gets passed in a custom header. In this case, the ADF REST runtime will ignore the declared, default framework version.
To process a request using a specific ADF REST framework version, the request must pass the custom header REST-Framework-Version
with the framework version number specified. For example, the following header specifies framework version 2 will be used to process the request that passes this version header.
REST-Framework-Version: 2
If the custom header is omitted on the request, then the ADF REST runtime uses the application’s default framework version, as defined in the adf-config.xml
file. When the application does not define a default framework version and the request on the service client omits the version header, then the base version (version 1) of the ADF REST framework is assumed.
The ADF REST runtime supports executing all requests on the service endpoint to affect the processing of the payload with functionality specific to the declared, default version of the ADF REST framework.
Note:
A framework version refers to a specific version of the ADF REST framework (corresponding to a particular Oracle JDeveloper release). For details about the ADF REST framework functionality supported in each framework version, see What You May Need to Know About Versioning the ADF REST Runtime Framework.
To ensure the service endpoint exposes the desired level of functionality to service clients, REST resource developers may optionally assign a default ADF REST framework version to each REST resource version named in the application’s adf-config.xml
file. Thus, when the request is made, the ADF REST runtime will process the request for the particular resource version according to the declaration in the adf-config.xml
file.
For example, the following URL specifies resource version 11.2
, where the application’s adf-config.xml
file associates this resource version with version 2 of the ADF REST framework. Because version 2 of the ADF REST framework supports rowmatch filter expressions, as a result, the ADF REST runtime will process the request with the appropriate functionality and fetch the departments with names that begin with SA
(for example, SALES) or have a Location
of BOSTON.
http://server/demo/rest/11.2/Departments?q=DepartmentName like 'SA*' or Location = 'BOSTON'
Note that a service client may override the default framework version and process individual requests using a specified framework version that gets passed in a custom header. In this case, the ADF REST runtime will ignore the application default. If the custom header is omitted on the request, then the ADF REST runtime always uses the application’s default framework version, as defined in the adf-config.xml
file. When the application does not define a default framework version and the request on the service client omits the version header, then the base version (version 1) of the ADF REST framework is assumed.
The ADF REST runtime supports the following advanced use cases:
Retrieving LOV attribute values in the context of an existing resource item.
Querying a resource with a partial get using filtering to restrict attributes.
Fetching the resource collection with a row finder.
Returning just the data of the resource item or resource collection.
Returning the estimated count of resource items in a resource collection.
Executing a custom action defined by view object client interface.
Overriding the HTTP method to perform an update
Making batch requests.
The ADF REST runtime supports retrieving a subset of fields from resource collections using a GET method.
The payload structure of nested child resource differs depending on the ADF REST framework version that has been registered for the ADF REST service client. For details about the ADF REST framework versions, see What You May Need to Know About Versioning the ADF REST Runtime Framework.
The following samples are based on two different versions of the Employees
resource and Departments
resource. The URL samples showing resource 11.0
reflect a response payload structure supported by ADF REST framework versions 1 and 2. While the URL samples showing resource 11.1
, reflect the response payload structure supported in ADF REST framework version 3 (and later). In both framework scenarios, the samples fetch the Employees
resource as a child of the Departments
resource.
Note:
SQL SELECT statements executed by the ADF REST resource’s backing view object are based on how the view object was created. Only view objects that the ADF Business Components developer creates with declarative SQL mode enabled support optimized SQL SELECT statements formed exclusively by the list of attributes named by the query parameter fields
. The SELECT statement executed by non-declarative view objects will contain all attributes of the view object definition. To gain this runtime optimization, it is therefore recommended that ADF Business Components developers create view objects for ADF REST resources using only declarative SQL mode.
ADF REST Framework Version 3 (and later)
Starting with version 3 of the ADF REST framework, the ADF REST runtime returns a nested child resource in the response payload as a resource collection, instead of as an array of resource items. This functionality, available in framework version 3 (and later), allows service clients to make a request for additional records after determining how many items were left unfetched in the initial request. The attributes hasMore
and count
on the child resource indicate whether more items may be returned from the resource collection. For details about using the pagination attributes from the response payload when you opt into ADF REST framework version 3, see Paging a Resource Collection.
The following sample illustrates functionality for ADF REST framework version 3 (and later). The response payload represents the nested child resource as a resource collection, where the collection object includes the hasMore
and count
attributes. A link is provided should it be necessary to query the child resource for additional resource items. In this sample, the response payload shows the hasMore
attribute is false
, suggesting that no items remain unfetched on the Employees child resource for either department 10 or department 20.
Request Made With Framework Version 3
URL
http://server/demo/rest/11.1/Departments?fields=DepartmentId;Employees:FirstName&onlyData=true
HTTP Method
GET
Content-Type
none
Payload
none
Response Made With Framework Version 3
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload
{ "items" : [ { "DepartmentId" : 10, "Employees" : { "items" : [ { { "FirstName" : "Jennifer" } } ], "count" : 1, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" }, ] }, { "DepartmentId" : 20, "Employees" : { "items" : [ { { "FirstName" : "Michael" }, { "FirstName" : "Pat" } } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" }, ] }, { ... ], "count" : 25, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments", "name" : "Departments", "kind" : "collection" } ]
ADF REST Framework Version 1 or Version 2
Version 1 and version 2 of the ADF REST framework return the nested child resource expanded in the response payload as an array of resource items. If the resource collection being fetched is large, several requests will be required to fetch all items.
The following samples fetch the attribute values for instances of the Departments
and Employees
collections. The query parameter fields
ensures the response payload contains only the specified attributes. Note that a GET request may return no values for any resource in the URL that does not specify an attribute value.
The first request (URL 1) fetches the values for an instance of the Employees
collection. The query parameter fields
ensures the response payload contains only the specified attributes: FirstName
, LastName
, and Email
.
The second request (URL 2) fetches the DepartmentId
values for instances of the Departments
collection and the FirstName
value for employees of each department. The query parameter onlyData
filters the response to hide child links.
The third request (URL 3) fetches the DepartmentId
values for instances of the Departments
collection, the FirstName
value for employees of each department, and the JobId
history for each employee. The query parameter onlyData
again filters the response to hide child links.
Request 1 Made With Framework Version 1 or 2
URL 1
http://server/demo/rest/11.0/Employees/101?fields=FirstName,LastName,Email
HTTP Method
GET
Content-Type
none
Payload
none
Response 1 From Framework Version 1 or 2
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload 1
{ "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.0/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] }
Request 2 Made With Framework Version 1 or 2
URL 2
http://server/demo/rest/11.0/Departments?fields=DepartmentId;Employees:FirstName&onlyData=true
HTTP Method
GET
Content-Type
none
Payload
none
Response 2 From Framework Version 1 or 2
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload 2
{ "items" : [ { "DepartmentId" : 10, "Employees" : [ { "FirstName" : "Jennifer" } ] }, { "DepartmentId" : 20, "Employees" : [ { "FirstName" : "Michael" }, { "FirstName" : "Pat" } ] }, { "DepartmentId" : 30, "Employees" : [ { "FirstName" : "Den" }, { "FirstName" : "Alexander" }, { "FirstName" : "Shelli" }, { "FirstName" : "Sigal" }, { "FirstName" : "Guy" }, { "FirstName" : "Karen" } ] }, { "DepartmentId" : 40, "Employees" : [ { "FirstName" : "Susan" } ] }, ... ], "count" : 25, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ]
Request 3 Made With Framework Version 1 or 2
URL 3
http://server/demo/rest/11.0/Departments?fields=DepartmentId;Employees:FirstName;Employees.JobHistory:JobId&onlyData=true
HTTP Method
GET
Content-Type
none
Payload
none
Response 3 From Framework Version 1 or 2
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourcecollection+json
Payload 3
{ "items" : [ { "DepartmentId" : 10, "Employees" : [ { "FirstName" : "Jennifer", "JobHistory" : [ { "JobId" : "AD_ASST" }, { "JobId" : "AC_ACCOUNT" } ] } ] }, { "DepartmentId" : 20, "Employees" : [ { "FirstName" : "Michael", "JobHistory" : [ { "JobId" : "MK_REP" } ] }, { "FirstName" : "Pat", "JobHistory" : [ { "JobId" : "AD_ASST" }, { "JobId" : "AC_ACCOUNT" } ] } ] }, { "DepartmentId" : 30, "Employees" : [ { "FirstName" : "Den", "JobHistory" : [ { "JobId" : "ST_CLERK" } ] }, { "FirstName" : "Alexander", "JobHistory" : [ { "JobId" : "AD_ASST" }, { "JobId" : "AC_ACCOUNT" } ] }, { "FirstName" : "Shelli", "JobHistory" : [ { "JobId" : "AD_ASST" }, { "JobId" : "AC_ACCOUNT" } ] ] ... ], "count" : 25, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
The ADF REST runtime supports applying a row finder to fetch a resource collection using a GET method. The ADF REST resource developer defines seeded filters called row finders. The ADF REST runtime supports passing parameters into these filters and supports using the seeded filters to reduce (or filter) the collection.
Filtering with a row finder is performed using the finder query string to specify one or more row finder parameter values. The finder with row finder query string parameter format is:
finder=<rowfinderName>;<attr1>=<value1>,<attr2>=<value2>,...
Example: finder=DeptByName;Dname=ACCOUNTING
The resource collection describe explains the shape of a row finder. To work with the row finder:
Execute the resource describe and locate the finders
attribute in the collection element. The name
attribute identifies the row finder definition name. Also locate the name of the row finder parameter under attributes
.
Execute a GET with the query parameter finder
and pass the row finder name and parameters.
For example, the Departments resources describe returns the following:
"collection" : { "rangeSize" : 25, "finders" : [ { "name" : "EmpByEmailFinder", "title" : "EmployeesByEmailVC", "attributes" : [ { "name" : "Email", "type" : "string", "updatable" : true, "required" : "Optional", "queryable" : false } ]
The following sample fetches the Departments
collection specified by a row finder EmpByEmailFinder
where the Email
attribute value NSMITH
is passed.
Request
URL
http://server/demo/rest/11.1/Employees?finder=EmpByNameFinder;Email=NSMITH
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "items" : [ { "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.1/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } ], "count" : 1, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "Employees", "kind" : "collection" } ] }
The ADF REST runtime supports retrieving only the data of resource items using a GET method of a resource collection or a resource item.
The following sample fetches the values of the Employees
collection attributes. The query parameter onlyData
ensures the representation is filtered to contain only data in the response payload and no links.
Request
URL
http://server/demo/rest/11.1/Employees?onlyData=true
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "items" : [ { "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000 }, { "EmployeeId" : 102, "FirstName" : "Lex", "LastName" : "De Haan", "Email" : "LDEHAAN", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 3000 }, { "EmployeeId" : 103, "FirstName" : "Alexander", "LastName" : "Hunold", "Email" : "AHUNOLD", "JobId" : "IT_PROG", "DepartmentId" : 60, "Salary" : 4000 }, { "EmployeeId" : 104, "FirstName" : "Bruce", "LastName" : "Ernst", "Email" : "BERNST", "JobId" : "IT_PROG", "DepartmentId" : 60, "Salary" : 5000 }, { "EmployeeId" : 105, "FirstName" : "David", "LastName" : "Austin", "Email" : "DAUSTIN", "JobId" : "IT_PROG", "DepartmentId" : 60, "Salary" : 6000 } ], "count" : 5, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "Employees", "kind" : "collection" } ] }
The ADF REST runtime supports retrieving the estimated number of resource items in resource collections using a GET method.
The following sample returns an estimated total result of 5
for the Employees
collection. The query parameter totalResults
ensures the response payload contains the totalResults
attribute.
Request
URL
http://server/demo/rest/11.1/Employees?totalResults=true&limit=2
HTTP Method
GET
Content-Type
none
Payload
none
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "items" : [ { "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 2000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/NSMITH", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/NSMITH", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.1/Employees/NSMITH/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] }, { "EmployeeId" : 102, "FirstName" : "Lex", "LastName" : "De Haan", "Email" : "LDEHAAN", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 3000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/LDEHAAN", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/LDEHAAN", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.1/Employees/LDEHAAN/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } ], "totalResults" : 5, "count" : 2, "hasMore" : true, "limit" : 2, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees", "name" : "Employees", "kind" : "collection" } ] }
The ADF REST runtime supports executing one or more custom actions that have been defined on the client interface of the resource's backing view object using a POST method.
The following sample executes the custom action multiplySalary
on an instance of the Employees
collection. In this case, the custom action has been defined on the view row client interface for the backing view object and therefore enables executing actions on row-level instances.
Request
URL
http://server/demo/rest/11.1/Employees/101
HTTP Method
POST
Content-Type
application/vnd.oracle.adf.action+json
Payload
{ "name": "multiplySalary", "parameters": [ { "multiplicand": "2" } ] }
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.actionresult+json
Payload
{ "result" : 4000.0 }
Some HTTP servers or clients do not support exposing all the methods in the HTTP specification. The ADF REST runtime allows you to use the popular POST method to carry out operations for other methods.
The following sample uses the POST method to update a Departments
resource item by overriding the PATCH method.
Request
URL
http://server/demo/rest/11.1/Departments/15
HTTP Method
POST
X-HTTP-Method-Override
PATCH
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "DepartmentName": "UpdatedDept", }
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.resourceitem+json
Payload
{ "DepartmentId" : 15, "DepartmentName" : "UpdatedDept", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/15", "name" : "Departments", "kind" : "item" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/11.1/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
The ADF REST runtime supports executing multiple operations in a single roundtrip using a batch request. The data is committed at the end of the request. However, if one request part in a batch request fails, then all changes are rolled back and an error response is returned.
The following sample illustrates a successful batch operation that executes operations in three parts.
Request
URL
http://server/demo/rest
HTTP Method
POST
Content-Type
application/vnd.oracle.adf.batch+json
Payload
{ "parts": [ { "id": "part1", "path": "/11.1/Employees/101", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part2", "path": "/11.1/Employees/102", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part3", "path": "/11.1/Employees/103", "operation": "update", "payload": { "Salary": 10000 } } ] }
Response
HTTP Code
200
Content-Type
application/vnd.oracle.adf.batch+json
Payload
{"parts": { { "id" : "part1", "path" : "/11.1/Employees/101", "operation" : "update", "payload" : { "EmployeeId" : 101, "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 10000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.1/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } }, { "id" : "part2", "path" : "/11.1/Employees/102", "operation" : "update", "payload" : { "EmployeeId" : 102, "FirstName" : "Lex", "LastName" : "De Haan", "Email" : "LDEHAAN", "JobId" : "AD_VP", "DepartmentId" : 90, "Salary" : 10000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/102", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/102", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.1/Employees/102/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } }, { "id" : "part3", "path" : "/11.1/Employees/103", "operation" : "update", "payload" : { "EmployeeId" : 103, "FirstName" : "Alexander", "LastName" : "Hunold", "Email" : "AHUNOLD", "JobId" : "IT_PROG", "DepartmentId" : 60, "Salary" : 10000, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/103", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/11.1/Employees/103", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/11.1/Employees/103/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } } ] }
The ADF REST framework supports HTTP methods, HTTP headers, request URL parameters, media types, and other concepts to enable making REST API calls on resources.
The HTTP payloads that are exchanged between the server and the client can be encoded. This feature is enabled when the client specifies an Accept-Encoding: gzip
header or Content-Encoding
header in the service request.
To disable encoding support for resources, you may set the custom property adf.rest.enablecompression
to false
. In JDeveloper, the property is set in the ADF configuration file (adf-config.xml
) of the Fusion web application.
Table 22-3 describes the content-encoding tokens supported by the ADF REST framework.
Table 22-3 Supported Content-Encoding Tokens
Content-Encoding | Description |
---|---|
|
Does not compress the payload. The behavior is the same as when the encoding is omitted. |
|
Compresses the payload using the format produced by the file compression program |
|
Compresses the payload with a combination of the |
Media types, also called MIME types or content types, define the allowed resource structure of the payload exchanged between the client and server. All ADF REST media types are based on JSON. Resources accessed in client applications fall under the application
type and json
subtype.
The service client invoking the REST API will interact with the RESTful web service using one of the media types listed in Table 22-4. The types are defined such that the media type does not vary with the view object definition backing the resource. Note that the value of the accept
header depends on the context of the invocation. Links to the JSON token structure of the ADF REST framework media types are provided in the following table.
Note:
As an alternative to specifying the supported media types, the service client request accept header can specify application/json
when a superset of all supported media types may be accepted in the response.
Table 22-4 Media Types Supported by the ADF REST Framework
Media Type | Invocation Context | Description |
---|---|---|
|
GET method POST method |
Represents the format for all resource collections returned by the ADF REST runtime. All attributes are automatically generated by the framework. Only the content of the For an example, see Describing a Resource Collection. |
|
GET method POST method DELETE method PATCH method |
Represents the format for all resource items returned by the ADF REST runtime. Only the attribute For an example, see Describing a Resource Item. |
|
POST method |
Describes custom action execution and their parameters. Exposed custom actions are backed by methods of a view object interface or view row interface. For an example, see Executing a Custom Action. |
|
POST method |
Describes the result of an action execution. For an example, see Executing a Custom Action. |
|
GET method |
Describes the resource and its elements. For an example, see Describing All Available Resources. |
|
POST method |
Describes a set of operations to be performed, where the operation consists of a set of parts and each part represents a request. The batch request is executed in one single transaction. For an example, see Making Batch Requests. |
|
GET method |
Describes the result of a request to get all versions of a resource. For an example, see Retrieving All Available Version Release Names. |
ADF REST data types are mapped by the ADF REST framework between ADF REST resource items and their backing ADF Business Components entity object attributes. At runtime, the framework exposes the data type of fetched ADF REST resource items as the describe attribute type
.
Table 22-5 shows the relationship between the ADF Business Components data types supported on entity object attributes backing the view object of ADF REST resources and the corresponding ADF REST data types that the ADF REST framework defines. In general, the framework defines the data type of an ADF REST resource item based on the SQL type of the attribute backing the resource item, with these two exceptions:
When the backing attribute is defined as a boolean type map, then the ADF REST type will always be a boolean.
When the backing attribute’s Java type is blob or clob, then the ADF REST type will be an attachment.
Table 22-5 Data Types Supported by the ADF REST Framework
ADF Backing Attribute | ADF REST Data Type |
---|---|
Where an attribute is configured with one of the following type maps:
|
boolean |
Java Class:
|
attachment |
SQL type: Char |
string |
SQL type: Number |
integer |
SQL type: Number (precision = *, scale > 0) |
number |
SQL type: Number (precision < 10, scale = 0) |
integer |
SQL type: Number (precision >= 10, scale = 0) |
integer |
SQL type: Date |
|
The ADF REST framework supports the HTTP codes listed in the following table. The specific code that is returned depends on the HTTP method invoked on the web service.
Table 22-6 HTTP Codes Supported by the ADF REST Framework
HTTP Code | Description |
---|---|
|
Request successfully executed and the response has content. |
|
Resource successfully created. The response contains the created resource. |
|
Request successfully executed and the response doesn't have content. |
|
According to the provided ETag, the resource was not modified. |
|
The request could not be understood by the server due to malformed syntax. |
|
The server is refusing to service the request because the resource of the request is secured and authentication has not yet been provided. |
|
The requested resource was not found. |
|
The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. |
|
The resource state in the server side doesn't match the provided ETag. |
|
The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. |
|
The server encountered an unexpected condition which prevented it from fulfilling the request. |
The ADF REST framework supports the HTTP headers listed in the following table.
Table 22-7 HTTP Headers Supported by the ADF REST Framework
HTTP Header Name | Description |
---|---|
|
Use to specify the content-type of the request/response payload. The ADF REST runtime is able to interpret (request/response) the media types, as described in ADF REST Media Types. |
|
Use to specify the content-encoding of the request/response payload. The ADF REST runtime is able to parse a compressed request that uses the encodings, as described in ADF REST Payload Compression Support. |
|
Use to specify the expected content-type of the response payload. The ADF REST runtime is able to interpret (request/response) the media types, as described in ADF REST Media Types. |
|
Use to specify the list of acceptable encoded responses. The ADF REST framework is able to generate a response using the encodings described in ADF REST Payload Compression Support. |
|
Use to specify the version of the ADF REST framework to use at runtime to process the request. The ADF REST framework version passed in the version header overrides the default framework declaration defined by the application in the |
|
Use to identify the URI of a newly created resource. The ADF REST framework includes the |
|
Use to compare the state of the resource in a request with the state of resource on the server. The ADF REST framework supports the |
|
Use to determine whether the state of the resource in a request is current with the resource on the server. This header is supported in order to execute conditional requests. See Checking for Data Consistency. |
|
Use to determine whether the state of the resource in a request does not match the current state on the server. This header is supported in order to execute conditional requests. See Checking for Data Consistency. |
|
Use to execute an action that is otherwise not supported by the server. This is a custom header (not defined by the HTTP specification) that contains the name of an HTTP method as its value. This value (if valid) will be used to define the HTTP method that will be used. This header will only be considered in a POST request. See Overriding the HTTP Method and Performing an Update. |
|
Use to avoid intermediate proxies to cache/store framework payloads. This header is configured for every HTTP response. Valid values are: It can either be set application-wide by specifying it as an In case finer control is needed, the value can be set on the resource tree and the header will be set accordingly. Currently, <pageDefinition ...> <parameters/> <executables/> <bindings> <tree ....> <ServiceConfiguration> <CacheControl> <MaxAge>30</MaxAge> </CacheControl> </ServiceConfiguration> <nodeDefinition ../> </tree> </bindings> </pageDefinition> The integer value supplied within Please note that this resource definition value will override the default setting and the setting made by the |
The ADF REST framework supports operations on the following HTTP methods.
GET
POST
PATCH
DELETE
The ADF REST framework supports the following operations using a GET method with the URI as shown.
Describe the resource collection, resource item, or resource catalog (when resource collection and resource item are omitted).
http://server/demo/rest/{version}/[{resourceCollectionPath}|{resourceItemPath}]/describe
Retrieve the resource collection representation with or without a query string parameter.
http://server/demo/rest/{version}/{resourceCollectionPath}[?{queryStringParam}[&{queryStringParam}]]
Retrieve the resource item representation with or without a query string parameter.
http://server/demo/rest/{version}/{resourceItemPath}[?{queryStringParam}[&{queryStringParam}]]
Retrieve a specific version of the resource collection, the latest resource version, or all available resources (when version identifier and resource collection are omitted).
http://server/demo/rest/[{version}|latest/{resourceCollectionPath}]
Request Parameters
The GET method supports query string parameters to query, filter, page, and sort the resource representation. The supported parameters are listed in the following table. All GET method URI parameters can be combined with any other parameter in the table, except where noted on the expand
and field
parameters. Note that query string parameters can only be used on resource media types. They cannot, for example, be used when describing the resource.
Note:
The results of the GET method or the query syntax may vary depending on the ADF REST framework version used for a client request. The following table specifies where the framework version is important to note when using query string parameters. For additional information about framework versions, see What You May Need to Know About Versioning the ADF REST Runtime Framework.
Table 22-8 Supported Resource Media Type GET Method Query String Parameters
GET URI Parameter | Resource Type (Item | Collection) | Value | Description |
---|---|---|---|
Starting in ADF REST framework version 2, |
resource collections only |
In framework version 1, the query parameter is used in the WHERE clause and contains one or more query by example-type expressions, separated by a semi-colon. Format: Example: Starting in framework 2, for richer querying support, the query parameter accepts a rowmatch expression format that identifies the specific rows to retrieve from the resource. The filter can be as simple as a single expression, or you can create more complex filters by combining expressions using the For example, the following expression uses conjunction to query the resource using three different fields:
If the query parameter value or expression contains any special character like ‘;’, ‘,’, ‘=’ (or similar), the value must be defined as a literal and enclosed in single quotes. For example:
Additionally, in version 1, if the query parameter expression contains any reserved word (such as AND or OR), then the quoted string must be delimited by a space character to separate it from other parameters in the query expression. For example, the string matching filter
Note that starting in framework version 2, the use of a space character is no longer required to delimit a string matching filter that contains a reserved word. For a complete explanation of the rowmatch expression format, see What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2. |
The resource collection will be queried using the provided expressions. Supported operators in framework version 1 and later:
Supported operators in framework version 2 and later also include:
Allowed special characters in framework version 1:
Allowed special characters in framework version 2 and later:
For an example of the usage supported in ADF REST framework version 1 and version 2, see Filtering a Resource Collection with a Query Parameter. For additional examples of rowmatch expressions, see What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2. |
|
resource collections only |
An expression containing information about the finder and its parameters. Format: Example: |
The resource collection will be queried using the provided finder/parameter. The list of available finders is provided in the describe. Finders with parameters whose type does not belong to For an example, see Filtering a Resource Collection with a Row Finder. |
Starting in ADF REST framework version 3 and later, For more information, see What Happens at Runtime: Invoking an ADF REST Framework Version. |
both |
A simple comma separate list of resource item attributes. Format: Example: May be used on child resources. Format: < Example: May be used on nested resources using accessor dot notation. Format: < Example: Or on both resources in the nested resource. Format: < Example: |
This parameter filters the resource item attributes. Only the specified attributes are returned. Note that if a nested resource is queried using the accessor dot notation ( Note this parameter cannot be combined with the For examples that uses version 1 or 2 of the ADF REST framework as compared to version 3 (and later), see Querying With Filtering Attributes (Partial Get). |
|
both |
boolean Default: |
The representation will be filtered in order to contain only data (no For an example, see Returning Only Resource Data in a Payload. |
|
resource collections only |
boolean Default: |
The resource collection representation will include the estimated row count when For an example, see Returning the Estimated Count of Resource Items. |
Starting in ADF REST framework version 3 and later, For more information, see What Happens at Runtime: Invoking an ADF REST Framework Version. |
both |
Display all children. Format: Display more than one child resource using a comma separate list of accessors. Format: < Example: Display nested resources using the accessor dot notation. Format: < Example: |
When this parameter is provided, the specified children are included in the resource payload (instead of the link). Note the Note that if a nested resource is queried using the accessor dot notation ( For examples that uses version 1 or 2 of the ADF REST framework as compared to version 3 (and later), see Fetching Nested Child Resources. |
|
resource collections only |
integer Default: Iterator binding |
This parameter restricts the number of resources returned inside the resource collection. If the limit exceeds the resource total results, then the framework will return the available resources. For an example, see Paging a Resource Collection. |
|
resource collections only |
integer Default: 0 (the first position) |
Used to define the starting position of the resource collection. If offset exceeds the resource count, then no resources are returned. For an example, see Paging a Resource Collection. |
|
both |
A set of dependency attributes. Format: Example: |
The dependencies are attributes that are set before and rolled back after generating the response. Generally, they are used to preview the effects of an attribute change as it applies to cascading LOV-enabled attributes. The dependencies attributes are always set in the resource item in question. When a child resource collection is requested and the |
|
both |
A comma separated list of order-by attributes with a sort flag to specify ascending or descending order. Format: Example: Default: ORDERBY attributes defined on the view object query backing the resource will be applied. |
Orders a resource collection based on its attributes. If the For an example, see Sorting a Resource Collection. |
|
both |
A comma separated list of Example: |
When a resource item or a resource collection is requested and the Note the |
|
Resource Catalog Describe |
A comma separated list of |
When a resource catalog describe is requested and the Note top-level resources can be hidden from a catalog describe by setting the <pageDefinition ...> <parameters/> <executables/> <bindings> <tree ....> <ServiceConfiguration Visibility="unlisted"/> <nodeDefinition ../> </tree> </bindings> </pageDefinition> |
|
Resource Item Describe |
boolean Default: Example: |
When a resource item describe is requested and For an example, see Describing a Resource Item and Describing a Nested Resource. |
Query String Operators Supported by ADF REST Data Types
The following table shows the ADF REST data types and the valid operators that may be used in query parameter strings. Note that the operators BETWEEN, NOT BETWEEN, IN, NOT IN, and the wildcard character % are available only starting in ADF REST framework version 2.
Table 22-9 Operators Supported by Data Types in Query (q) Parameter Strings
ADF REST Data Type | Supported Operator |
---|---|
integer |
|
number |
|
string |
|
date |
|
time |
|
datetime |
|
boolean |
|
Media Types Supported
Request
None
Response
application/vnd.oracle.adf.resourcecollection+json
: When retrieving a resource collection.
application/vnd.oracle.adf.resourceitem+json
: When retrieving a resource item.
application/vnd.oracle.adf.description+json
: When describing a resource.
application/vnd.oracle.adf.version+json
: When retrieving all available resource versions.
Use Case Samples
Checking for Data Consistency When Retrieving ADF REST Resource Items
Retrieving LOV-Enabled Attribute Values for Existing Resource Items
ADF REST Framework Version Overview
The ADF REST framework supports the following operations using a POST method with the URI as shown.
Create a new resource.
http://server/demo/rest/{version}/{resourceCollectionPath}
Execute an action on a resource collection or resource item.
http://server/demo/rest/{version}/{resourceCollectionPath}|{resourceItemPath}
Execute an a batch request.
http://server/demo/rest/{version}/{resourceCollectionPath}
Request Parameters
none
Media Types Supported
Request
application/vnd.oracle.adf.resourceitem+json
: When creating a resource or overriding the HTTP method to perform an update.
application/vnd.oracle.adf.action+json
: When executing an action.
application/vnd.oracle.adf.batch+json
: When executing a batch request.
Response
application/vnd.oracle.adf.resourceitem+json
: When executing an action or creating a resource.
application/vnd.oracle.adf.actionresult+json
: When executing an action that has an object to return.
application/vnd.oracle.adf.batch+json
: When executing an batch request.
Use Case Samples
The ADF REST framework supports the following operation using a PATCH method with the URI as shown.
Updating a resource item.
http://server/demo/rest/{version}/{resourceItemPath}
Request Parameters
none
Media Types Supported
Request
application/vnd.oracle.adf.resourceitem+json
: The resource item to be updated.
Response
application/vnd.oracle.adf.resourceitem+json
: The updated resource item.
Use Case Samples