22 Consuming ADF RESTful Web Services
This chapter includes the following sections:
About the ADF REST Framework
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 CRUD operations available, 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.
ADF REST Resource Use Cases and Examples
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 REST API framework that will be used to process requests. The version header allows you to override the default version declaration defined by the web application. By specifying the REST API framework version, the web application developer may opt into framework enhancements made by Oracle.
-
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-Overrideheader using a POST request method when client restrictions prevent the use of standard HTTP methods to interact with the REST resource. -
Merging payload content with the REST resource using a POST method in combination with a header
Upsert-Modeset to true. This action implements create if the record does not exist or update if the record exists. -
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.
-
Obtaining a error responses in the form of a JSON payload with exception detail when ADF REST framework version 4 or later is enabled. Alternatively, with framework version 3 or earlier, error responses are in the form of a simple message string.
-
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.xmlfile 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.xmlfile for the application. In JDeveloper starting with release 12.2.1.2.0, versions 1, 2, and 3 exist. In the release 12.2.1.4.0 and later, versions 1, 2, 3, 4, 5, 6, and 7 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 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.
Additional Functionality for RESTful Web Services
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, 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.
About the Resource Samples in This Chapter
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
Description of "Figure 22-1 REST Sample Project - ADF Business Components View Instances"
Sample Project Files and Data Model
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
Description of "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
Description of "Figure 22-3 REST Sample Project - Application Module Data Model"
Sample Project Resources and Resource Version Identifiers
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
Description of "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
Description of "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
Description of "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
Description of "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
Description of "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
Description of "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
Description of "Figure 22-10 REST Sample Project - Employees Resource Version 11.2"
Entity Object and View Object Customization
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
Description of "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
Description of "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
Description of "Figure 22-13 REST Sample Project - Employees BLOB Content Type"
As Figure 22-14 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-14 REST Sample Project - Departments Change Indicator Attribute
Description of "Figure 22-14 REST Sample Project - Departments Change Indicator Attribute"
Understanding ADF Business Components Resources
-
A
Departmentsresource is based on aDepartmentsVOview instance and its accessor to anEmployeesVOview instance. -
An
Employeesresource is based on anEmployeesVOview 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 |
Retrieving the ADF REST Catalog Describe
The describe for the RESTful web service resource catalog allows you to identify the shape and actions allowed on an ADF RESTful web service defined for the service endpoint. By default the catalog describe request returns a JSON object that contains the information needed to understand all available public resources, including their attributes, collections, items, annotations, actions, and links.
The ADF REST framework supports the following catalog describe use cases:
-
Retrieve the full resource catalog describe, including all resource details, such as their attributes, collections, items, annotations, actions, and links.
-
Retrieve a minimal resource catalog describe, where the describe details will be limited to resource titles and links only and children, or nested resources, will be excluded.
-
Retrieve a resource catalog describe (either full or minimal) based on resource visibility. For example, you can retrieve the describe for only public resources, only private (unlisted) resources, or both public and private resources.
-
Retrieve a resource catalog describe (either full or minimal) but optionally exclude or include children resources nested within a parent resource and optionally exclude or include all resource annotations.
To retrieve the catalog describe of all the available, public resources of a specific version in the application, you append /describe to the version URL.
For example, the following URL returns the describe for the resource catalog of all available public resources designated as version 11.0 in the identified application:
http://host:port/context-root/rest/11.0/describeNote:
Executing a GET request to retrieve a resource catalog describe 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.
When you do not require an exhaustive describe that returns the full set of information for all resources in the same request, you can request a minimal describe. For example, the following URL with query parameter metadataMode set to minimal returns the describe for all parent resources but the retrieved describe information will be limited to just the titles and links of the resources:
http://host:port/context-root/rest/11.0/describe?metadataMode=minimalAdditionally, you can append URL query parameters on the request for a minimal catalog describe to retrieve specific details in the describe. For example, the following URL with appended query parameters retrieves a minimal catalog describe with all available children resources nested within their parent resources included.
http://host:port/context-root/rest/11.0/describe?metadataMode=minimal&includeChildren=trueThe following table identifies the URL query parameters the may be used with the catalog describe request. These query parameters let you control the amount of detail retrieved in the describe.
Table 22-2 Optional URL Query Parameters for Catalog Describe Requests
| URL Query Parameter | Values | Description |
|---|---|---|
|
|
|
Use to retrieve the description of resources with or without all details. By default, the full catalog is retrieved, performing an exhaustive describe that returns the complete set of information for all resources, including nested children resources. The full catalog describe therefore includes the following sections of information for each resource: title, attributes, collection, item, annotations, children, and links Note that annotations must be defined by the ADF REST resource developer in the application and may not be present on the resource. You can improve the readability of a large catalog and retrieve a shallow catalog limited to the titles and links of parent resources (does not include children resources) by appending the URL parameter If you do not want any metadata in the response but only self links, you can append Optionally, additional parameters may be appended to the minimal describe request to include children resources and / or resource annotations, as explained for the query parameters |
|
|
(default depends on whether full or minimal catalog is retrieved) |
Use to either exclude or include resource annotations, as specified in the application. The default depends on the
metadataMode parameter value:
Note that annotations must be defined by the ADF REST resource developer in the application and may not be present on the resource You cannot use this parameter with |
|
|
(default depends on whether full or minimal catalog is retrieved) |
Use to either exclude or include all available children resources nested within a parent resource. The default depends on the
metadataMode parameter value:
You cannot use this parameter with |
|
|
|
Use to retrieve the description of resources of a certain visibility, as declared in the application. This URL parameter values specify including only public resources (
|
|
|
A comma separated list of resource collection names. Format: Example: |
Use to retrieve the description of the named resources to filter resources at the catalog level. |
Retrieving the Full Catalog Describe
ADF REST runtime supports describing all available resources for the application end point using a GET method and performs an exhaustive describe that returns the full set of information for all resources, including all children resources nested within parent resources.
To examine all available resources with full information included in the resource catalog:
-
Execute the resource catalog describe and locate the names of the resources in the describe. The
childrenattribute identifies nested resources. -
Examine these resource objects to understand the shape of each resource:
-
attributesspecifies the list of available resource collection attributes. -
collectionspecifies the shape of the collection and specifiesfindersfor row finder,links, and availableactions(including media types). -
itemspecifies the shape of the instances of the collection and itself specifieslinksand availableactions. -
childrenspecifies any nested resources (and itself containsattributes,collection, anditemobjects).
-
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.
Note:
You can use theinclude query parameter to retrieve the full catalog describe with resources of a certain visibility. For example, to view both public and private resources, you can usehttp://server/demo/rest/v1/describe?include=all. You can use all, unlisted, or public as values for the include query parameter.
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" : "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" : "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" : "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" : "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" : "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" } ] } } }
Retrieving a Minimal Catalog Describe
ADF REST runtime supports describing all available resources while retrieving a reduced amount of information for the application end point using a GET method. The reduced or minimal catalog describe helps improve the readability of the describe by limiting the resource information to resource titles, links, and available annotations.
To examine the minimal describe for all available resources in the resource catalog:
-
Execute the minimal resource catalog describe and locate the names of the resources in the describe. Note that nested resources or children resources are not shown by default.
-
Examine these resource objects
links.
For example, the minimal describe for a service with a Departments resource returns the following objects:
{
"Resources" : {
"Departments" : {
Departments,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.1/Departments/describe",
"name" : "self",
"kind" : "describe"
} ]
},
...
}
}By default children resources are not included in the minimal describe. Use the includeChildren query parameter to retrieve the minimal catalog describe with all available children resources nested within the parent resources. For example, to view children resources in the minimal describe, you can use a request like the following:
http://server/demo/rest/11.1/describe?metadataMode=minimal&includeChildren=trueThe minimal describe with the includeChildren query parameter set to true for a service with a Departments resource that includes a child resource Employees returns the following objects:
{
"Resources" : {
"Departments" : {
Departments,
"children" : {
"Employees" : {
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.1/Departments/{id}/child/Employees/describe",
"name" : "self",
"kind" : "describe"
} ]
}
},
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/11.1/Departments/describe",
"name" : "self",
"kind" : "describe"
} ]
},
...
}
}The following sample retrieves a minimal resource catalog describe, including children resources, where the Employees resource is nested within the Departments resource and the JobsLOV resource is nested in the Employees resource.
Request
-
URL
http://server/demo/rest/11.1/describe?metadataMode=minimal&includeChildren=true -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
Response
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.description+json -
Payload
{ "Resources" : { "Employees" : { "children" : { "JobsLOV" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/{id}/child/JobsLOV/describe", "name" : "self", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/describe", "name" : "self", "kind" : "describe" } ] } }, "Departments" : { "children" : { "Employees" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/describe", "name" : "self", "kind" : "describe" } ] } } }
Retrieving the Catalog Describe Based on Resource Visibility Declaration
ADF REST runtime supports describing all available resources with a URL parameter that includes resources of a certain visibility for the application end point using a GET method, optionally including those resources that the application identifies as private.
By default, only resources that are public are shown in the describe. This URL parameter can specify only public resources, only private (unlisted) resources, or both types. To view private resources, you must append either ?include=all (both public and private resources) or ?include=unlisted (only private resources) on the describe request.
For more information about how the application developer declares visibility in the resource definition, see How to Hide a Resource from the Catalog Describe.
To view private resources in the resource catalog:
-
Execute the resource catalog describe with the URL parameter
?include=allor?include=unlistedand locate the names of the private resources in the describe. -
Examine these resource objects to understand the shape of each resource:
The following sample retrieves a minimal resource catalog describe, including both public and private resources, where the Locations resource is configured as unlisted.
Request
-
URL
http://server/demo/rest/11.1/describe?metadataMode=minimal&include=all -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
Response
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.description+json -
Payload
{ "Resources" : { "Employees" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Employees/describe", "name" : "self", "kind" : "describe" } ] }, "Departments" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Departments/describe", "name" : "self", "kind" : "describe" } ] }, "Locations" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.1/Locations/describe", "name" : "self", "kind" : "describe" } ] } } }
Retrieving the ADF REST Resource Describe
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 a single resource collection.
-
Describe a single resource item.
-
Describe a nested resource in a parent-child relationship.
-
Describe two or more named resource collections.
-
Describe all available resources (resource catalog). For details, see Retrieving the ADF REST Catalog Describe.
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
Describing a Resource Collection
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:
-
attributesspecifies the list of available resource collection attributes. -
collectionspecifies the shape of the collection and specifiesfinderfor row finder,links, and availableactions(including media types). -
itemspecifies the shape of the instances of the collection and itself specifieslinksand availableactions. -
childrenspecifies any nested resources (and itself containsattributes,collection, anditemobjects).
-
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" : "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" : "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" : "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" } ] } } }
Describing a Resource Item
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
childrenattribute identifies nested resources. -
Examine the resource item describe to understand its shape.
-
attributesspecifies the list of available resource collection attributes. -
itemspecifieslinksto the item, including defined child collections, and availableactions. -
linksspecifies 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" : "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" } ] } } }
Describing a Nested Resource
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
childrenattribute identifies nested resources. -
Examine these resource objects to understand the shape of each resource:
-
attributesspecifies the list of available resource collection attributes. -
collectionspecifies the shape of the collection and specifiesfinderfor row finder,links, and availableactions(including media types). -
itemspecifies the shape of the instances of the collection and itself specifieslinksand availableactions. -
childrenspecifies the nested resources (and itself containsattributes,collection, anditemobjects).
-
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" : "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" : "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" : "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" : "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" } ] } } }
Describing Multiple Resource Collections
REST APIs support describing two or more named resource collections.
To examine the resource collections:
-
Execute the resource collection describe with the named resources using the
resourcesquery parameter. -
Locate the names of the resources in the describe.
-
Examine these resource objects to understand the shape of each resource:
-
attributesspecifies the list of available resource collection attributes. -
collectionspecifies the shape of the collection and specifiesfindersfor row finder,links, and availableactions(including media types). -
itemspecifies the shape of the instances of the collection and itself specifieslinksand availableactions. -
childrenspecifies any nested resources (and itself containsattributes,collection, anditemobjects).
-
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 uses the resources query parameter to describe version 11.0 of the Departments and Employees resources named on the request.
Request
-
URL
http://server/demo/rest/11.0/Departments/describe?resources=Departments,Employees -
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" : "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" : "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" : "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" } ] } "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" : "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" : "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" } ] } } }
Partially Describing a Nested Resource Collection
The ADF REST runtime supports obtaining a partial describe for a nested resource using a GET method and the parameter partialDescription to limit the depth of the hierarchy to the next child resource only.
The partialDescription parameter used with a describe request ensures the response payload contains only the nested collection to a depth of one nested object in the nested parent-child hierarchy. The describe for a child of the nested parent resource is not expand and provides only a link to retrieve that partial describe for the next resource in the hierarchy.
To examine the partial describe of a nested resource collection and its child resource, if any:
-
Execute the nested resource collection describe with the
partialDescriptionparameter and locate the name of the nested resource in the describe. -
Examine these resource objects to understand the shape of the resource. Specifically examine the
childrenelement to identify the partial describe link for the next child resource in the resource hierarchy (to a depth of one nested resource).-
attributesspecifies the list of available resource collection attributes. -
collectionspecifies the shape of the collection and specifiesfinderfor row finder,links, and availableactions(including media types). -
itemspecifies the shape of the instances of the collection and itself specifieslinksand availableactions. -
childrenidentifies any nested resource to a depth of one object and contains a describe link with the?partialDescriptionparameter to retrieve its partial description (this child resource describe specifically does not contain theattributes,collection, anditemobjects).
-
For example, the partial describe for the nested Employees resource returns the following objects. Note that in this sample, the Employees collection contains the child collection Bonus. The partial describe request limits the depth to the nested resource and a single child of the nested resource, in this case, Bonus.
{
"Resources" : {
"Employees" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Bonus" : {
"$ref" : "http://server/demo/rest/12.0/Departments/describe?partialDescription=Employees.Bonus"
} ],
...
"links" : [ {
} ]
}
}
The following sample retrieves a partial describe of version 12.0 of the nested Employees resource and contains a link to retrieve the partial describe for the next child in the resource hierarchy, Bonus.
Request
-
URL
http://server/demo/rest/12.0/Departments/describe?partialDescription=Employees -
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, "ServiceConfiguration" : { "Cache-Control" : "max-age=30" }, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 6 }, { "name" : "FirstName", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 20 }, { "name" : "LastName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 25 }, { "name" : "Email", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 25 }, { "name" : "PhoneNumber", "type" : "string", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 20 }, { "name" : "HireDate", "type" : "datetime", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always" }, { "name" : "JobId", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 10 }, { "name" : "Salary", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 8, "scale" : 2 }, { "name" : "CommissionPct", "type" : "number", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 2, "scale" : 2 }, { "name" : "ManagerId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 6 }, { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 4 } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourcecollection+json", "application/json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "upsert", "method" : "POST", "header" : "Upsert-Mode=true", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Bonus" : { "$ref" : "http://server/demo/rest/12.0/Departments/describe?partialDescription=Employees.Bonus" } } "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } }
Describing a Resource Collection with Specified Fields
The ADF REST runtime supports obtaining a limited describe for resource collections using a GET method and the parameter fields. The fields parameter used with a describe request ensures the response payload contains only the specified attributes of the collection.
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:
-
attributesspecifies the list of available resource collection attributes. -
collectionspecifies the shape of the collection and specifiesfinderfor row finder,links, and availableactions(including media types). -
itemspecifies the shape of the instances of the collection and itself specifieslinksand availableactions. -
childrenspecifies any nested resources (and itself containsattributes,collection, anditemobjects).
-
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 samples show retrieving a limited describe for version 12.0 of the Departments and nested Employees resources. The first request (URL 1) uses the fields parameter to retrieve a single attribute of the Departments resource collection. The second request (URL 2) uses the fields parameter and retrieves all attributes of the Departments resource collection by specifying the wildcard character (*) and then also retrieves the single EmployeeId attribute of the nested Employees child resource collection.
Request
-
URL 1
http://server/demo/rest/12.0/Departments/describe?fields=DepartmentNameURL 2
http://server/demo/rest/12.0/Departments/describe?fields=*;Employees:EmployeeId -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
Response
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.description+json -
Payload 1
{ "Resources" : { "Departments" : { "discrColumnType" : false, "attributes" : [ { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "precision" : 30 } ], "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/12.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" : "upsert", "method" : "POST", "header" : "Upsert-Mode=true", "requestType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ], "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ] }, { } ] }, "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.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" : "delete", "method" : "DELETE" } ] }, "children" : { "Employees" : { "$ref" : "http://server/demo/rest/12.0/Departments/describe?partialDescription=Employees" } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }Payload 2
{ "Resources" : { "Departments" : { "discrColumnType" : false, "ServiceConfiguration" : { "Cache-Control" : "max-age=30" }, "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 4 }, { "name" : "DepartmentName", "type" : "string", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 30 }, { "name" : "ManagerId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 6 }, { "name" : "LocationId", "type" : "integer", "updatable" : true, "mandatory" : false, "queryable" : true, "allowChanges" : "always", "precision" : 4 } ], "collection" : { "rangeSize" : 25, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "DepartmentId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 4 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourcecollection+json", "application/json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "upsert", "method" : "POST", "header" : "Upsert-Mode=true", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] } ] }, "item" : { "links" : [ { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "children" : { "Employees" : { "discrColumnType" : false, "ServiceConfiguration" : { "Cache-Control" : "max-age=30" }, "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 6 } ], "collection" : { "rangeSize" : 0, "finders" : [ { "name" : "PrimaryKey", "attributes" : [ { "name" : "EmployeeId", "type" : "integer", "updatable" : true, "mandatory" : true, "queryable" : true, "allowChanges" : "always", "precision" : 6 } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourcecollection+json", "application/json" ] }, { "name" : "create", "method" : "POST", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "upsert", "method" : "POST", "header" : "Upsert-Mode=true", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] } ] }, "item" : { "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/12.0/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" } ], "actions" : [ { "name" : "get", "method" : "GET", "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "update", "method" : "PATCH", "requestType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ], "responseType" : [ "application/vnd.oracle.adf.resourceitem+json", "application/json" ] }, { "name" : "delete", "method" : "DELETE" } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }
Using ETags in Describe Requests
ETags provide the ability for service clients to determine the metadata changes in the web server since the last time it fetched the describe. This is accomplished by returning an ETag header in the response of a describe request.
An ETag is an identifier assigned by a web server to a specific version of a REST resource describe. If the REST resource describe representation ever changes, a new and different ETag is assigned. ETags are used in the HTTP header and are unique. For more information on using ETags, see Checking for Data Consistency.
When the REST resource describe is retrieved, the web server will return the REST resource's current representation along with its corresponding ETag value, which is placed in an HTTP response header ETag field. For example:
ETag: "5265766973696F6E33"The client may cache the representation, along with its ETag. If the client wants to retrieve the same describe again, it will send its previously saved copy of the ETag along with the request in a If-None-Match field. For example:
If-None-Match: "5265766973696F6E33"On this subsequent request, the server compares the client's ETag with the ETag for the current version of the resource. If the ETag values match, which indicates that the resource has not changed, then the server sends a response with a HTTP 304 Not Modified status. This status indicates that the cached version is good for use.
The following samples describe the ETag behavior for the employees resource.
Example 22-1 When ETag Values Match
Request
-
URL
/rest/v1/employees/describe -
HTTP Method
GET
-
If-None-Match
"5265766973696F6E33" -
Metadata-Context
label=latest -
Payload
none
Response
-
HTTP Code
304 -
ETag
"5265766973696F6E33" -
Metadata-Context
label="Revision3" -
Payload
none
Example 22-2 When ETag Values Do Not Match
Request
-
URL
/rest/v1/employees/describe -
HTTP Method
GET
-
If-None-Match
"5265766973696F6E33" -
Metadata-Context
label=latest -
Payload
none
Response
-
HTTP Code
200 -
ETag
"5265766973696F6E34" -
Metadata-Context
label="Revision4" -
Payload
{ "Resources" : { "employees" : { ... } } }
Note:
ETags are not returned if the request metadata context is not configured to read the latest MDS label.
Retrieving Resource Versions
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 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.
Retrieving All Available Release Version Names
The ADF REST runtime supports retrieving the release version names defined for the service end point using a GET method.
To examine the release version names:
-
Execute the service end point describe and locate the available release version names in the describe.
-
Examine these elements to understand the order of the release versions:
-
versionspecifies the version name, as defined in theadf-config.xmlfile. -
isLatestproperty specifies the version name of the most recent release version. -
predecessor-versionspecifies the link to the previous release version. -
successor-versionspecifies the link to the next latest release version. -
currentspecifies the link to the most recent release version.
-
-
Optionally, examine these elements to understand the version of the ADF REST framework version that will be used to process requests for a specific release version:
-
defaultFrameworkVersionproperty specifies the default ADF REST framework version that has been associated with a particular release version, as optionally defined by the ADF REST resource developer in theadf-config.xmlfile. Note that a new ADF REST framework version may introduce new functionality. Thus, associating a specific framework version with each release version ensures that service clients interact with the appropriate level of functionality. See Working with ADF REST Framework Versions. -
allowedFrameworkVersionsproperty specifies the list of ADF REST framework versions that are supported for a particular release version. Service clients may override the default framework version with any value in the list by specifying the value in theREST-Framework-Versionheader.
-
For example, the describe for a service end point with two release versions returns the following objects:
{
"items" : [
{
"version" : "version_identifier_latest",
"isLatest" : true,
"adf:extension" : {
"defaultFrameworkVersion" : "framework_identifier",
"allowedFrameworkVersions" : [ "framework_identifier1", "framework_identifier2", ... ]
},
"links" : [
{
"rel" : "self",
...
},
{
"rel" : "canonical",
...
},
{
"rel" : "predecessor-version",
...
},
{
"rel" : "describe",
...
}
]
},
{
"version" : "version_identifier_previous",
"adf:extension" : {
"defaultFrameworkVersion" : "framework_identifier",
"allowedFrameworkVersions" : [ "framework_identifier1", "framework_identifier2", ... ]
},
"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. Note that links of type predecessor-version and successor-version specify the location of each release version relative to their position in the list of versions. 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 3. Note that a framework version refers to a specific version of the ADF REST framework, corresponding to a particular Oracle JDeveloper release, where a new framework version introduces new functionality.
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" : "3", "allowedFrameworkVersions" : [ "1", "2", "3" ] }, "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", "allowedFrameworkVersions" : [ "1", "2", "3" ] }, "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", "allowedFrameworkVersions" : [ "1", "2", "3" ] }, "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" } ] }
Retrieving a Resource By a Specific Version
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" : "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" : "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" } ] } } }
Retrieving the ADF REST Resource
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.
- Fetching a resource collection or resource item and grouping item details under the
@contextelement.
Fetching a 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" } ] }
Paging a Resource 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" : 2 "offset" : 4, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/11.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
Filtering a Resource Collection with Primary Key Values
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
findersattribute in the collection element. Thenameattribute identifies the finder asPrimaryKey. Also locate the name of the primary key attributes underattributes. -
Execute a GET with the query parameter
finderand pass the primary key attributes using the finder namePrimaryKey.
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" } ] }
Filtering a Resource Collection with a Query Parameter
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, reserved 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 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" } ] }
Fetching a Resource Item
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" } ] }
Fetching Nested Child Resources
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 } ] }, ... ] }
Sorting a Resource Collection
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:desc,attribute2
In order to perform case-insensitive sorting on a resource collection using a GET method, the orderBy query string parameter must follow this format:
upper(<orderBy_attribute1_name>):<(asc)> or lower(<orderBy_attribute2_name>)
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" } ] }
Fetching a Resource with Grouped Context Information
ADF REST runtime supports fetching a resource using a GET method and retrieving the payload with resource fields and resource item context information, like links, grouped separately when your request is enabled to use ADF REST framework version 6.
Starting with version 6 of the ADF REST framework, a @context element is introduced in the response payload for resource requests to help you to more easily differentiate between resource fields and the context information of individual items. This element helps to organize the response payload of the GET request by grouping information together for each item.
Compared to earlier framework versions (5 and earlier), the following changes to a GET request payload result with framework version 6 or later:
-
A new
@contextsection appears below the list of fields of each item of the resource and contains identifying information for the item, as well as links. -
A new
keyelement appears within the@contextsection and contains the unique identifier of the specific resource item as a string. -
The
linkssection within the@contextsection no longer list any properties, likechangeIndicator. -
The
changeIndicatorvalue is moved toETag, which is under aheaderselement within the@contextsection.
The following sample fetches the Departments resource collection and three items with context information for each item under the @context element.
Collection Request Example Made With Framework Version 6
-
URL
http://server/sample/rest/12.0/Departments -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
Collection Response Example Made With Framework Version 6
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourcecollection+json -
Payload
{ "items" : [ { "DepartmentId" : 10, "DepartmentName" : "Administration", "@context" : { "key" : "1", "headers" : { "ETag" : "ACED00C78" }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] } }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "@context" : { "key" : "2", "headers" : { "ETag" : "ACED00B74" }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] } }, { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "@context" : { "key" : "3", "headers" : { "ETag" : "ACED001E8" }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] } } ], "count" : 3, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments", "name" : "Departments", "kind" : "collection" } ] }
The following sample fetches all fields of an instance of the Departments resource collection with context information for each item under the @context element.
Item Request Example Made With Framework Version 6
-
URL
http://server/demo/rest/12.0/Departments/50 -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
Item Response Example Made With Framework Version 6
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DepartmentId" : 50, "DepartmentName" : "Shipping", "@context" : { "key" : "1", "headers" : { "ETag" : "ACED00G26" }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/12.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/12.0/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/12.0/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } }
Creating a Resource Item
The ADF REST runtime supports the following creation use cases:
-
Creating a resource item in collection.
-
Creating a child resource item.
Creating a Resource Item in a Collection
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" } ] }
Creating a Child Resource Item
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 -
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" } ] }
Updating a Resource 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" } ] }
Updating or Creating Resource Items (Upsert)
Using a POST method with Upsert mode enabled, the ADF REST runtime supports updating resource items that exist, and if not, creating the resource items.
You use a POST method with header variable Upsert/true to enable the Upsert functionality that creates an ADF REST resource if this resource does not exist or updates the resource if the resource exists. You select the Create and Update checkboxes on the user interface to enable this action (Upsert). If the header variable Upsert/true is not provided, or is set to Upsert/false, then the Upsert functionality is disabled. Also, if only the Create checkbox is selected or only the Update checkbox is selected, then POST creates or updates a resource if permissions for these actions are allowed. Note that Upsert will work as intended only if both Create and Update options are enabled on the resource.
The following sample creates (through Upsert) a new Department resource item with a child Employee resource item.
Request
-
URL
http://server/demoapp/rest/1.0/Departments -
HTTP Method
POST -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
HTTP Header
Upsert-Mode/true -
Payload
{ "Deptno": 80, "Dname": "ENG80", "Emp": [{ "Empno": 8080, "Ename": "Smith", "Mgr": 8080 }] }
Response
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Content Encoding
Null -
Payload
{ "Deptno": 80, "Dname": "ENG80", "Emp": [{ "Empno": 8080, "Ename": "Smith", "Mgr": 8080 }] }
The following sample demonstrates the update process (through Upsert). In the response payload, a Department (Dept) resource item’s AltKey namely Dname is utilized. Similarly, the Employee (Emp) child resource item’s Altkey namely Email is utilized. The Dname Altkey (Dname=ENG80) is used to locate and load the required Department (Dept 80). The request then updates this Department’s Location (Loc). The Email Altkey is used to locate and load the Employee child resource item (Emp 8080) and the request payload updates this Employee child resource item’s Sal and Job attributes. The request payload also contains a second Employee child resource item (Emp 9080). The Ename key is used to locate this second Employee child resource item. If found, this second Employee child resource item’s Sal and Job attributes get updated. If this second Employee child resource item does not exist, the request payload creates this second Employee child resource item.
Request
-
URL
http://server/demoapp/rest/1.0/Departments -
HTTP Method
POST -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
HTTP Header
Upsert-Mode/true -
Payload
{ "Dname": "ENG80", "Loc": "HQ-altkey", "Emp": [{ "Email": "smith@xyz.com", "Sal": 8000, "Job": "ENGINEER1" }, { "Empno": 9080, "Ename": "John", "Sal": 9000, "Job": "SALES1" } ] }
Response
-
HTTP Code
200 -
Content Type
application/vnd.oracle.adf.resourceitem+json -
Content Encoding
Null -
Payload
{ "Deptno": 80, "Dname": "ENG80", "Loc": "HQ-altkey", "TrEmpno": null, "Emp": [{ "Empno": 8080, "Ename": "Smith", "Job": "ENGINEER1", "Email": "smith@xyz.com", "Hiredate": null, "Sal": 8000, "Comm": null, "Deptno": 80 }, { "Empno": 9080, "Ename": "John", "Job": "SALES1", "Mgr": 9080, "Hiredate": null, "Sal": 9000, "Comm": null, "Deptno": 80 } ] }
Deleting a Resource Item
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
Checking for Data Consistency
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"
} ]
}
Checking for Data Consistency When Updating ADF REST Resource Items
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:
-
Query one or more resource items and, for each returned resource item, obtain the ETag value from the
changeIndicatorproperty in thepropertiessection of the response. When querying multiple resource items, there will not be a single ETag response header. Instead, the ETag for each of the items in the response will be in thepropertiessection.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" } ] }
-
Update the resource item, using a PATCH request 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. This occurs in production web applications when multiple users simultaneously access the same resource item. For example, when user 1 and user 2 both query the same item, the item has, for example, ETag value 1. Then, if user 1 successfully updates the item with ETag value 1, and user 2 attempts to update the same item with ETag value 1, the attempt will fail.
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" } ] }
Checking for Data Consistency When Retrieving ADF REST Resource Items
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:
-
Query one or more business object items and, for each returned resource item, obtain the ETag value from the
changeIndicatorproperty in thepropertiessection of the response.When querying multiple business object items, there will not be a single ETag response header. In the case of ADF REST framework versions 5 and earlier, the ETag for each of the items in the response will be in the
propertiessection. In the case of framework versions 6 and later, the ETag for each of the items will be in the@contextelement that serves to group all the information for an item in one section. The following sample shows the response with a framework version before version 6 enabled.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" } ] } -
Query one or more business object items 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
304state 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 (Made With Framework Version 5 or Earlier)
{ "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" } ] }Payload 2 (Made With Framework Version 6 or Later)
{ "DepartmentId" : 10, "DepartmentName" : "Administration", "RelState" : null, "@context" : { "key" : "AB8765BCD", "headers" : { "ETag" : "responseETag123." }, "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" } ] }
Working with Attachments
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
enclosurelink type to point to a resource that cannot be represented with the supported payload types (such asimage/png). -
Encoded into
Base64string 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
Streaming Attachments Using a Resource Item Enclosure Link
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
enclosurelink for the desired attribute. Theitemsection 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.
Note:
The URL that you specify for enclosure should be the enclosure link for the image and not the URL of the image.
{
"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
Replacing LOB Content Using Base64
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" } ] }
Working with LOV
The ADF REST runtime supports the following LOV-enabled attribute use cases.
-
Retrieving non-dependent LOV-enabled attribute values for a standalone LOV.
Refer to this use case when you need to allow users to update an LOV-enabled resource item in the context of a known containing resource item.
-
Retrieving nested LOV-enabled attribute values for cascading LOVs.
Refer to this use case when you need to allow users to update a nested LOV resource item based on a dependent LOV-enabled attribute.
Note that the use case procedure changed starting with ADF REST Framework version 5. In earlier Framework versions, the REST request depended on the use case. However, starting with Framework version 5, all LOV use cases, standalone or cascading, rely on row finders URLs that you enable for static LOV resources.
Retrieving Non-Dependent LOV-Enabled Attribute Values with Framework Versions 1 Through 4
In ADF REST Framework version 4 and earlier, the runtime supports retrieving the values from LOV-enabled attributes in the context of a known containing resource item using a GET method.
In ADF REST Framework versions 4 and earlier, the resource item for an LOV-enabled attribute nests a child LOV resource URL that you can use to obtain the list of values that are based on the context of the already known containing resource item.
Note:
Starting with ADF REST Framework version 5, the use of row finder URLs to populate a LOV resource item is recommended. See Retrieving LOV-Enabled Attribute Values with Framework Version 5 and Later.When you need to populate cascading LOV attribute lists, in ADF REST Framework versions 4 and earlier, see Retrieving Dependent LOV-Enabled Attribute Values with Framework Versions 1 Through 4.
In Framework version 4 and earlier, to work with LOV-enabled attributes in non-cascading lists:
-
Execute the resource describe and locate the following details about the LOV:
Under the
lovdescription of a resource attribute, locate thechildRefproperty to identify the child resource collection that contains the LOV choices. Note that the resource describe of a LOV child resource does not show thelovdescription, as the operation to retrieve LOV-enabled attribute values is not supported on LOV child resources.The
lovdescription 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 asderived = true. Finally, thelovdescription 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
linkselement and locate the link with areloflovand thehrefthat identifies the corresponding LOV child resource (as specified in the resource itemchildRefproperty).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
lovdescription. 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 Made With Framework Version 4 or Earlier
-
URL
http://server/demo/rest/11.0/Employees/101/lov/JobsLOV?onlyData=true&fields=JobTitle -
HTTP Method
GET
-
Content-Type
none
-
Payload
Response Returned By Framework Version 4 or Earlier
-
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" } ] }
Retrieving Dependent LOV-Enabled Attribute Values with Framework Versions 1 Through 4
In ADF REST Framework version 4 and earlier, the runtime supports retrieving LOV-enabled attribute values using a GET method when it is necessary to populate a resource item without a row context, such as when supporting dependent LOV-enabled attribute lists, also known as cascading LOVs.
In ADF REST Framework versions 1 through 4 the describe provides a static LOV URL to access the dependent list without the context of a known row, where the selection the end user makes in one LOV determines the list to display in the nested LOV. Representing two lists of States and Cities is an example of cascading LOVs, where the list to display for the Cities LOV child attribute is not know until the State LOV attribute selection has been made. In this case, the ADF REST resource developer working in the Model project defines static LOV resources that do not require a row context to enable access to the nested LOV attribute list in the resource describe. For details about creating a static LOV resource in the Model project, see How to Support Create Operations on ADF REST Resources with LOV Attributes.
When you need to populate a non-dependent LOV attribute list (a single LOV) in ADF REST Framework versions 1 through 4, see Retrieving LOV-Enabled Attribute Values for Existing Resource Items.
Note:
Starting with ADF REST Framework version 5, the use of row finder URLs to populate a LOV resource item is recommended. With version 5 enabled, only top-level LOV resources are supported, where the resource describe provides no URL to access nested LOV child resources. See Retrieving LOV-Enabled Attribute Values with Framework Version 5 and Later.In Framework version 4 and earlier, to work with dependent LOV-enabled attributes:
-
Execute the resource describe and locate the following details about the LOV:
Under the
lovdescription of an attribute, locate thelovResourcePathproperty to identify the LOV resource that contains the LOV choices. Note that the resource describe of a LOV child resource does not show thelovdescription, as the operation to retrieve LOV-enabled attribute values is not supported on LOV child resources.The
lovdescription 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 asderived = true. Finally, thelovdescription 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
linkselement and locate the link with areloflovand thehrefthat identifies the LOV resource (as specified in thelovResourcePathproperty).Note the
lovResourcePathis 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 resourcesCountriesandStates, 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: lovandname: 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: childandname: 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
lovdescription. 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 Made With Framework Version 4 or Earlier
-
URL
http://server/demo/rest/11.0/Jobs?onlyData=true&fields=JobTitle -
HTTP Method
GET
-
Content-Type
none
-
Payload
Response Returned By Framework Version 4 or Earlier
-
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" } ] }
Retrieving LOV-Enabled Attribute Values with Framework Version 5 and Later
In ADF REST Framework version 5 and later, the runtime supports retrieving values from LOV-enabled attributes using a GET method by passing in the containing resource item which may be either already known or based on a selection made at runtime in a dependent LOV attribute list.
The row finder URL supports obtaining the LOV list of a single LOV or of cascading LOVs, where the selection the end user makes in one LOV determines the list to display in the nested LOV. Representing two lists of States and Cities is an example of cascading LOVs, where the list to display for the Cities LOV child attribute is not know until the State LOV attribute selection has been made. In this case, the ADF REST resource developer working in the Model project defines static LOV resources that do not require having a row context to enable access to the nested LOV-enabled attribute list in the resource describe. For details about creating a static LOV resource in the Model project, see How to Support Create Operations on ADF REST Resources with LOV Attributes.
The row finder URL that you obtain from the resource describe and pass on a GET request allows you to submit a bind parameter value to specify the containing resource and give the LOV-enable attribute its row context. In the case of a cascading LOVs, once you have retrieved the dependent LOV attribute values, you can populate the nested LOV list by using a POST request with the retrieved values as the payload.
Note:
Starting with ADF REST Framework version 5, the use of row finder URLs to populate a LOV resource item is recommended. Unlike earlier versions of the framework, the use of row finder URLs in the describe supports both dependent and non-dependent LOVs. For details about working with LOVs with earlier framework versions, see instead Retrieving Non-Dependent LOV-Enabled Attribute Values with Framework Versions 1 Through 4 and Retrieving Dependent LOV-Enabled Attribute Values with Framework Versions 1 Through 4.In Framework version 5 and later, to work with LOV row finder URLs:
-
Execute the resource describe and locate the following details about the LOV:
Under the
lovdescription of an attribute, locate thechildRefForCreateproperty to identify the LOV resource that contains the LOV choices.The
lovdescription 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 asderived = true. Finally, thelovdescription 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 item describe
linkselement and locate the link with areloflovand thehreffor the parent LOV list. -
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
lovdescription. 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 states). -
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.
-
To get the values to display for a dependent LOV attribute, use a LOV resource link (as specified in the
childRefForCreateproperty) with parametrized row finder for the selected resource item. Execute a GET using the LOV resource link (rel: lovandname: CityLOVForCreate) in the selected resource item. This will retrieve a resource collection with the list of values (cities) based on the parent LOV resource (states).
For example, the Address resource collection describe returns the following:
{
"Resources" : {
"Address" : {
"discrColumnType" : false,
"attributes" : [ {
...
}, {
"name" : "City",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 32,
"controlType" : "choice",
"maxLength" : "32",
"lov" : {
"childRef" : "CityLOV",
"childRefForCreate" : "CityLOVForCreate",
"attributeMap": [ {
"source" : "CityName",
"target" : "City"
}],
"displayAttributes" : [ "CityName" ],
}
}, {
"name" : "State",
"type" : "string",
"updatable" : true,
"mandatory" : true,
"queryable" : true,
"precision" : 2,
"controlType" : "choice",
"maxLength" : "2",
"lov" : {
"childRef" : "StateLOV",
"childRefForCreate" : "StateLOVForCreate",
"attributeMap": [ {
"source" : "StateCode",
"target" : "State"
}],
"displayAttributes" : [ "StateCode" ],
}
}, {
...
},
"item" : {
"links" : [ {
...
}, {
"rel": "lov",
"href": "http://server/demo/rest/11.0/Address/{id}/lov/CityLOV",
"name": "CityLOV",
"kind": "collection"},
}, {
"rel" : "lov",
"href" : "http://server/demo/rest/11.0/Cities?finder=ByStateFinder%3BstateVar%3D{State}",
"name" : "CityLOVForCreate",
"kind" : "collection"
}, {
}, {
"rel": "lov",
"href": "http://server/demo/rest/11.0/Address/{id}/lov/StateLOV",
"name": "StateLOV",
"kind": "collection"},
}, {
"rel" : "lov",
"href" : "http://server/demo/rest/11.0/States",
"name" : "StateLOVForCreate",
"kind" : "collection"
}, {
...
The following sample fetches the values for the parent LOV display attribute StateCode from the States LOV resource collection. The query parameters onlyData and fields ensure the representation is filtered to contain only data in the response payload, where CA and TX are examples of the values of the display attribute StateCode.
LOV Request Made With Framework Version 5
-
URL
http://server/demo/rest/11.0/States?onlyData=true&fields=StateCode -
HTTP Method
GET
-
Content-Type
none
-
Payload
LOV Response Returned By Framework Version 5
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourcecollection+json -
Payload
{ "items" : [ { "StateCode" : "CA" }, { "StateCode" : "TX" }, { "StateCode" : "MS" }, { ... } ] }
Where the usage involves a cascading LOV, this sample fetches the values for the dependent LOV with the LOV display attribute CityName from the Cities LOV resource collection. The row finder takes a parameter for the state name CA returned in the client for the parent LOV.
Dependent LOV Request Made With Framework Version 5
-
URL
http://server/demo/rest/11.0/Cities?finder=ByStateFinder%3BstateVar%3D{State}" -
HTTP Method
GET
-
Content-Type
none
-
Payload
Dependent LOV Response Returned By Framework Version 5
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourcecollection+json -
Payload
{ "items": [{ "Statecode": "CA", "Cityname": "Tracy" }, { "Statecode": "CA", "Cityname": "Pleasanton" }, { "Statecode": "CA", "Cityname": "Jackson" }, { "Statecode": "CA", "Cityname": "San Jose" }, { ... } ] }
Working with ADF REST Framework Versions
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 theadf-config.xmlfile. -
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. Note that service clients may override the default framework version with another framework version identifier by specifying the value in the REST-Framework-Version header. The allowedFrameworkVersions property lists the values of the available framework versions.
{
"items" : [
{
"version" : "11.2",
"isLatest" : true,
"adf:extension" : {
"defaultFrameworkVersion" : "2",
"allowedFrameworkVersions" : [ "1","2","3","4","5","6","7" ]
},
"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.
Retrieving ADF REST Framework Versions for Resource Versions
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
versionproperty to identify the release version. -
Examine the associated
defaultFrameworkVersionproperty to understand the version of the ADF REST framework that will be used to execute requests for the specific release version:-
defaultFrameworkVersionproperty specifies the default ADF REST framework version that has been associated with a particular release version, as optionally defined by the ADF REST resource developer in theadf-config.xmlfile. Note that a new ADF REST framework version may introduce new functionality. Thus, associating a specific framework version with each release version ensures that service clients interact with the appropriate level of functionality. See Working with ADF REST Framework Versions.
-
-
If you want to override the default framework version, examine the
allowedFrameworkVersionsproperty to understand what versions that you may use:-
allowedFrameworkVersionsproperty identifies the list of ADF REST framework versions that are supported for a particular release version. Service clients may override the default framework version with any value in the list by specifying the value in theREST-Framework-Versionheader.
-
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_identifier",
"allowedFrameworkVersions" : [ "framework_identifier1", "framework_identifier2", ... ]
},
"links" : [
{
"rel" : "self",
...
},
{
"rel" : "canonical",
...
},
{
"rel" : "predecessor-version",
...
},
{
"rel" : "describe",
...
}
]
},
{
"version" : "version_identifier_previous",
"adf:extension" : {
"defaultFrameworkVersion" : "framework_identifier",
"allowedFrameworkVersions" : [ "framework_identifier1", "framework_identifier2", ... ]
},
"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" : "3", "allowedFrameworkVersions" : [ "1", "2", "3", "4" ] }, "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", "allowedFrameworkVersions" : [ "1", "2", "3", "4" ] }, "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", "allowedFrameworkVersions" : [ "1", "2", "3", "4" ] }, "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" } ] }
Executing a Request Using the Header to Specify the Framework Version
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.
Executing Requests Using the Declared Default Framework Version
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.
Working with Warning and Error Responses
Error responses can be obtained in the form of a JSON payload with exception details when ADF REST framework version 4 or later is enabled. Alternatively, with framework version 3 or earlier, error responses are in the form of a simple message string.
Warning responses can be obtained in the form of a JSON payload with details when ADF REST framework version 6 or later is enabled.
In addition to HTTP status codes and error messages, it is possible to obtain exception details in the response when your request is enabled to use ADF REST framework version 4 and the request is made for either application/vnd.oracle.adf.error+json or application/json media types. With framework version 4, the response will be in the form an exception detail payload which provides the following benefits to the service client:
-
If multiple errors occur in a single request, the details of each error are presented in a hierarchical structure.
-
An application-specific error code may be present that identifies the ADF exception corresponding to each error.
-
An error path may be present that identifies the location of each error in the request payload structure.
Note:
The exception detail may or may not present certain details, such as the application-specific error code and the request payload’s error path.
For example, compare the error response for a POST submitted with a payload that contains the following incorrectly formatted date field when framework version 3 (or earlier) is enable and when framework version 4 (or later) is enabled.
{ "EmpNum" : 5027,
"EmpName" : "John",
"EmpHireDate" : "not a date"
}Standard Error Response, Version 3 and earlier
Without framework version 4, no response payload is generated and instead only a single error message that does not reference the request payload will be returned in the response.
"An instance of type oracle.jbo.domain.Date cannot be created from string not a date. The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm."
Exception Payload Error Response, Version 4 and later
With framework version 4 enabled, the following exception detail payload is generated for the response. The payload includes the usual HTTP status code and formats the details of one or more exceptions in an array structure.
{ "title" : "Bad Request",
"status" : "400",
"o:errorDetails" : [ {
"detail" : "An instance of type oracle.jbo.domain.Date cannot be created from string not a date.
The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm.",
"o:errorCode" : "26099",
"o:errorPath" : "/EmpHireDate"
} ]
}Exception Payload Warning Response, Version 6 and later
With framework version 6 enabled, a warning detail payload is generated for the response similar to the following. The payload includes the usual HTTP status code and formats the details of the warning in the @context section for each resource item.
"@context" : {
...
} ],
"warnings": [ {
"detail": "Warning from overridden validateEntity method in DeptImpl : DeptName = ABC or DEF"
}, {
"detail": "Attribute set with value 50 for DeptNum in Dept failed",
"o:errorCode": "27011",
"o:errorPath": "/DeptNum"
}, {
"detail": "Warning from overridden create method in DeptViewDefRowImpl"
}, {
"detail": "Warning from overridden afterCommit method in DeptViewImpl"
} ]
}
}Understanding the Exception Payload Error Response
-
ADF REST framework version is version 4.
-
Either
application/vnd.oracle.adf.error+jsonorapplication/jsonis an acceptable media type for the response.
The exception detail payload is a JSON object with the following structure as determined by the ADF REST framework:
{ "title" : "Message as per HTTP status code",
"status" : "HTTP error code",
"o:errorDetails" : [
...
{
"detail" : "Message of detail error",
"o:errorCode" : "error code"
"o:errorPath" : "JSON pointer to the location of the error in the request payload"
},
...
]
}You opt into the exception payload as the error responses by using framework version 4 and making a request for either the application/vnd.oracle.adf.error+json media type or application/json media type.
Note that within the exception payload, o:errorDetails can vary as per the number and the types of errors encountered. Additionally, the error code and error path are not guaranteed to be present in the response payload and should not be relied upon by service clients.
Obtaining the Standard Error Message Response
The ADF REST runtime generates an error message that describes the validation or system error when the request is made with ADF REST framework versions 1 through 3 enabled.
Before version 4 of the ADF REST framework, the error response returns a single error message and HTTP status code. Version 4 and later allows service clients to obtain an error response with a detailed exception payload.
The following sample attempts to create the Departments object with a new department record. However, for this example the request fails because the record for the department instance already exists. The response is an error message because ADF REST framework version 4 (or later) is not enabled.
Request Example Made With Framework Version 3
-
URL
http://server/demo/rest/11.2/Departments -
HTTP Method
POST
-
Accept Header
application/vnd.oracle.adf.resourceitem+json,application/json -
Payload
{ "DeptNum" : 50, "DeptName" : "SALES", }
Response Example From Framework Version 3
-
HTTP Code
400 -
Error Response
A department with the same name already exists. Please provide a different name.
Obtaining an Exception Payload Error Response
The ADF REST runtime supports obtaining exception details in the response when your request is enabled to use ADF REST framework version 4 and the request is made with an appropriate media type.
Starting with version 4 of the REST API framework, web applications may obtain an error response with a detailed exception payload.
Notice in the exception payload the o:errorDetails array provides the error path for where the error occurred in the request object; however, these particular details may not always be available to web applications.
The following sample attempts to create the department object with a new department item. However, for this example the request fails because the item for the department already exists.
Request Example 1 Made With Framework Version 4
-
URL
http://server/demo/rest/11.2/Departments -
HTTP Method
POST
-
Accept Header
application/vnd.oracle.adf.resourceitem+json,application/json -
Payload
{ "DeptNum" : 50, "DeptName" : "SALES", }
Response Example 1 From Framework Version 4
-
HTTP Code
400 -
Content-Type
application/json -
Payload
{ "title" : "Bad Request", "status" : "400", "o:errorDetails" : [ { "detail" : "A department with the same name already exists. Please provide a different name.", "o:errorCode" : "Dept_Rule_0" } ] }
The following sample attempts to create the department object with a new department item. However, for this example the request fails because the employee names entered exceed the number of characters allowed by the validation rule defined for the EmpName field.
Request Example 2 Made With Framework Version 4
-
URL
http://server/demo/rest/11.1/Departments -
HTTP Method
POST
-
Accept Header
application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json -
Payload
{ "DeptNum" : 52, "DeptName" : "newDept522", "Employees" : [ { "EmpNum" : 501, "EmpName" : "MILLERSxxxxxxxxxxxxxxxxx" }, { "EmpNum" : 502, "EmpName" : "JONESPxxxxxxxxxxxxxxxxx" } ] }
Response Example 2 From Framework Version 4
-
HTTP Code
400 -
Content-Type
application/vnd.oracle.adf.error+json -
Payload
{ "title" : "Bad Request", "status" : "400", "o:errorDetails" : [ { "detail" : "Value MILLERSxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.", "o:errorCode" : "27040", "o:errorPath" : "/Employees/0/EmpName" }, { "detail" : "Value JONESPxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.", "o:errorCode" : "27040", "o:errorPath" : "/Employees/1/EmpName" } ] }
The following sample attempts to perform a batch operation. However, for this example the batch operation fails for the reasons shown in the exception detail payload of the error response.
Request Example 3 Made With Framework Version 4
-
URL
http://server/demo/rest/11.1 -
HTTP Method
POST
-
Accept Header
application/vnd.oracle.adf.batch+json,application/vnd.oracle.adf.error+json -
Payload
{ "parts": [ { "id": "part1", "path": "/Employees", "operation": "create", "payload" : { "EmpNum" : 1299, "EmpJob" : "CLERK", "EmpMgr" : 7566, "EmpHireDate" : null, "EmpSal" : 245, "EmpComm" : 0, "EmpDeptNum" : 30 } }, { "id": "part2", "path": "/Employees", "operation": "create", "payload": { "EmpNum" : 7589, "EmpName" : "SampleEmpxxxxxxxxxxxxxxxxxx", "EmpJob" : "CLERK", "EmpMgr" : 7566, "EmpHireDate" : null, "EmpSal" : 245, "EmpComm" : 0, "EmpDeptNum" : 30 } }, { "id": "part3", "path": "/Departments", "operation": "create", "payload": { "DeptNum" : 52, "DeptName" : "newDept522", "Employees" : [ { "EmpNum" : 7588, "EmpName" : "SampleEmpxxxxxxxxxxxxxxxxxx", "EmpJob" : "CLERK", "EmpMgr" : 7566, "EmpHireDate" : null, "EmpSal" : 245, "EmpComm" : 0, "EmpDeptNum" : 30 } ] } }, { "id": "part4", "path": "/Departments/10/child/Loc", "operation": "get" }, { "id": "part5", "path": "/Departments?invQP=invVal", "operation": "get" }, { "id": "part6", "path": "/Departments/54", "operation": "delete" }, { "id": "part7", "path": "/1.0/Departments/54", "operation": "get" } ] }
Response Example 3 From Framework Version 4
-
HTTP Code
400 -
Content-Type
application/vnd.oracle.adf.error+json -
Payload
{ "title" : "Bad Request", "status" : "400", "o:errorDetails" : [ { "detail" : "URL request parameter invQP cannot be used in this context.", "o:errorCode" : "27520" }, { "detail" : "Attribute EmpName in Emp is required.", "o:errorCode" : "27014", "o:errorPath" : "/parts/0" }, { "detail" : "Value SampleEmpxxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.", "o:errorCode" : "27040", "o:errorPath" : "/parts/1/payload/EmpName" }, { "detail" : "Attribute EmpName in Emp is required.", "o:errorCode" : "27014", "o:errorPath" : "/parts/1" }, { "detail" : "Value SampleEmpxxxxxxxxxxxxxxxxxx for field EmpName exceeds the maximum length allowed.", "o:errorCode" : "27040", "o:errorPath" : "/parts/2/payload/Employees/0/EmpName" }, { "detail" : "Attribute EmpName in AM.Dept_empWorksIn_deptToEmpQA_EmpViewDef is required.", "o:errorCode" : "27014", "o:errorPath" : "/parts/2" }, { "detail" : "Not Found", "o:errorCode" : "11404", "o:errorPath" : "/parts/3" } ] }
Obtaining Warning Messages in the Payload Response
The ADF REST runtime supports obtaining warning details in the response when your request is enabled to use ADF REST framework version 6 and the request is made with an appropriate media type.
Starting with version 6 of the REST API framework, web applications may obtain a warning response with a response payload.
Notice in the exception payload the o:errorPaths element provides the error path for where the error occurred in the request object; however, these particular details depend upon validation rules set on the entity object backing the resource.
The following sample attempts to create the department object with a new department item. However, for this example the request fails because the DeptName for the department is specified as not allowed in the validation method of the Departments entity object.
Request Example 1 Made With Framework Version 6
-
URL
http://server/demo/rest/12.0/Departments -
HTTP Method
POST
-
Accept Header
application/vnd.oracle.adf.resourceitem+json,application/json -
Payload
{ "DeptNum" : 50, "DeptName" : "ABC", }
Response Example 1 From Framework Version 6
-
HTTP Code
201 -
Content-Type
application/json -
Payload
... "@context" : { ... } ], "warnings": [ { "detail": "Warning from overridden validateEntity method in DeptImpl : DeptName = ABC or DEF" }, { "detail": "Attribute set with value 50 for DeptNum in Dept failed", "o:errorCode": "27011", "o:errorPath": "/DeptNum" }, { "detail": "Warning from overridden create method in DeptViewDefRowImpl" }, { "detail": "Warning from overridden afterCommit method in DeptViewImpl" } ] } }
The following sample attempts to create the department object with a new department item. However, for this example the request fails because the employee salary entered does not meet the salary allowed by the validation rule defined for the EmpSalary field.
Request Example 2 Made With Framework Version 6
-
URL
http://server/demo/rest/11.1/Departments -
HTTP Method
POST
-
Accept Header
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DeptNum" : 52, "DeptName" : "newDept522", "Employees" : [ { "EmpNum" : 501, "EmpName" : "MILLER "EmpSalary" : "85" } ] }
Response Example 2 From Framework Version 6
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.error+json -
Payload
... "@context" : { ... } ], "warnings": [ { "detail": "Warning from Emp entity expressionValidator : Salary value is < 100.", "o:errorCode": "ExcTooLow", "o:errorPath": "/Employees/10" }, ] } }
Advanced Operations
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.
-
Overriding the HTTP method to perform an update
-
Making batch requests.
Querying With Filtering Attributes (Partial Get)
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" } ] }
Filtering a Resource Collection with a Row Finder
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
findersattribute in the collection element. Thenameattribute identifies the row finder definition name. Also locate the name of the row finder parameter underattributes. -
Execute a GET with the query parameter
finderand 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" } ] }
Returning Only Resource Data in a Payload
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" } ] }
Returning the Estimated Count of Resource Items
The ADF REST runtime supports retrieving the estimated item count in the resource collection.
The following sample estimates the total records and queries the first two items in the Employee 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" } ] }
Overriding the HTTP Method and Performing an Update
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" } ] }
Making Batch Requests
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.
A batch request can consist of a combination of create, update, delete, upsert, and get requests. The path parameter and the payload needs to be the same as what you use to invoke the request directly. The get method supports the same URL parameters in the batch request as a separate HTTP request.
The following sample illustrates a successful batch operation that executes operations in four parts: 1) update employee 101, 2) update employee 102, 3) update employee 103, 4) query employee 101.
Request
-
URL
http://server/demo/rest/11.1 -
HTTP Method
POST
-
Content-Type
application/vnd.oracle.adf.batch+json -
Payload
{ "parts": [{ "id": "part1", "path": "/Employees/101", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part2", "path": "/Employees/102", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part3", "path": "/Employees/103", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part4", "path": "/Employees?q=EmployeeId%3D101", "operation": "get" }] }
Response
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.batch+json -
Payload
{ "parts": [{ "id": "part1", "path": "http://server/demo/rest/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": "http://server/demo/rest/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": "http://server/demo/rest/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" }] } }, { "id": "part4", "path": "http://server/demo/rest/11.1/Employees", "operation": "get", "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" }] } }] }
ADF REST Framework Reference
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.
ADF REST Describe links Object Structure
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"
}rel Attribute Values
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-3.
Table 22-3 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. Use the |
|
|
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 |
href Attribute Value
The href attribute defines the URL to the linked resource or resource describe.
cardinality Attribute Values
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.
ADF REST API Framework Versions
A framework version refers to a specific version of the ADF REST framework available starting in a particular Oracle JDeveloper release.
The ADF REST runtime supports clients to specify a framework version that affects the processing of the payload or indicate the default framework version (as configured by the server) to be used. When you specify a framework version to process requests, it allows clients to opt into those features when they are ready. For example, to support both rowmatch expressions (offered in framework version 2 and later) and the query-by-example syntax (version 1 only), you would need to associate framework version 2 (or later) with a new release version identifier that you define in the web application. For example, in the URL samples given below, you can preserve the original functionality for release version 11.0 and expose the new functionality for version 11.1. This assumes that web application has declared framework version 2 the default on release version 11.1. Alternatively, if your web application will no longer require the functionality of your current framework version, you may associate the new framework version with your existing release version identifier. Therefore, you are not required to increment the release version to make use of a new framework version. 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 Framework.
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.
Note:
Each ADF REST framework version after version 1 introduces functionality that the previous framework versions does not support. Thus, when you choose to opt into a later framework version, the REST API of your application may introduce backward incompatible changes on the service client consuming the REST API. In the table below, see the Does Not Support column for backward compatibility issues.
The following table explains the changes for each framework version.
Table 22-4 ADF REST API Framework Versions
| REST API Framework Version | Supports | Does Not Support | Examples |
|---|---|---|---|
|
1 - Default version. Use to process requests for web applications when no other version is specified |
Supports query-by-example resource query syntax Filtering resource collections using the |
|
|
|
2 - You must specify the version for the request. Only then the REST API support the use of expanded expression syntax to process the request. |
Supports more advanced query syntax for making REST API calls. Interprets Supports filtering resource collections using |
Query-by-example resource query syntax is not compatible. Introduces a backward incompatible change to web application that rely on Framework version 1. |
See What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2 |
|
3 - The payload structure represents nested child resource as a resource collection, instead of an array of items as in version 1 and 2 |
Supports retrieving nested child resources with payload attributes that may be used by the web application to determine whether more resource items would be returned in a subsequent REST API request. Supports pagination of nested child resource that would otherwise require more than one request to fetch. Exposes functionality that allows |
Introduces a backward incompatible change to web application that rely on Framework version 1 or 2. |
See Querying With Filtering Attributes (Partial Get). Also see Obtaining the Standard Error Message Response for error response. |
|
4 – Possible to obtain exception details in the response when your request is enabled to use REST API framework version 4 and the request is made for either |
Supports the response in the form an exception detail payload that provides the following benefits to the web application:
|
The exception detail may or may not present certain details, such as the application-specific error code and the request payload’s error path. |
|
|
5 - Possible to share the LOVs that may not depend on the row context to filter out records. Also possible to share the LOVs with multiple resources. LOV resources will be represented by its own top-level resource and the row context LOV URLs are no longer returned in the payload and in the describe. |
Removes the dependency of LOVs to be nested inside a resource parameters in the LOV resource URL. Enhanced support for request and response parameters beyond the current supported types of string, number, date, and boolean. |
Nested levels of LOV resource URL. |
See What You May Need to Know About Configuring LOV Resources for Row Finders. The supported Java types include |
|
6 - Supports differentiation between the resource fields and the item context information like links and headers. Also displays warnings in the response payload in the context section for create/upsert and update actions. |
Non-attribute fields like
|
...
"@context" : {
"key" : "AB8765BCD",
"headers" : {
"ETag" : "ACED..."
...
},
"links": [ {
"rel": "self",
"href":
...
} ]
"warnings": [ {
"detail": "Warning from overridden validateEntity method in DeptImpl : DeptName = ABC"
}, {
"detail": "Attribute set with value 92 for DeptNum in Dept failed",
"o:errorCode": "27011",
"o:errorPath": "/DeptNum"
}, {
"detail": "Warning from overridden afterCommit method in DeptViewImpl"
}, {
"detail": "Warning from overridden afterCommit method in DeptViewImpl"
} ]
}
} |
|
|
7 - Provides an option to remove row-level LOV resource descriptions in describe and from the resource item payload links section. |
Supports the use of top-level LOV resource links |
Row context LOVs in the describe and payloads |
ADF REST Payload Compression Support
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-5 describes the content-encoding tokens supported by the ADF REST framework.
Table 22-5 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 |
ADF REST Media Types
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-6. 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-6 Media Types Supported by the ADF REST Framework
| Media Type | Invocation Context | Description |
|---|---|---|
|
|
GET 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 PATCH method |
Represents the format for all resource items returned by the ADF REST runtime. Also represents the format for a resource item in a POST or PATCH request payload. Only the attribute For an example, see Describing a Resource Item. |
|
|
POST method |
Describes the result of an action execution. |
|
|
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. |
|
|
any |
Describes the exception payload error response for a request made with an error. To use this media type and obtain the exception details in an error response payload, the request must be made with ADF REST framework version 4 (or later) enabled. For an example, see Obtaining an Exception Payload Error Response. |
ADF REST Data Types
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-7 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-7 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 |
Java Class: java.util.List supported starting in ADF REST framework version 5
|
array |
Java Class: java.util.Map supported starting in ADF REST framework version 5
|
object |
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 REST service accepts the |
ADF REST HTTP Codes
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-8 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. |
ADF REST HTTP Headers Support
The ADF REST framework supports the HTTP headers listed in the following table.
Table 22-9 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. |
|
|
The presence of this header is enforced for every request when the anti-CSRF mechanism is turned on. The anti-CSRF mechanism can be turned on by setting the value of the |
|
|
Use to avoid intermediate proxies to cache/store framework payloads. This header is configured for every HTTP response. The value, by default, turns off caching, and the framework sends the response header: However, an application developer may override the default behavior by configuring the resource definition. The value can be set on the resource tree and the header will be set accordingly. Currently, <seconds></MaxAge>, if set in the resource tree. The following sample of a resource definition file shows how to set the value.<pageDefinition ...>
<parameters/>
<executables/>
<bindings>
<tree ....>
<ServiceConfiguration>
<CacheControl>
<MaxAge>30</MaxAge>
</CacheControl>
</ServiceConfiguration>
<nodeDefinition ../>
</tree>
</bindings>
</pageDefinition>The integer value supplied within If configured on the resource definition, the |
|
|
Use Upsert-Mode:true in a request that uses POST to create a resource item if the resource item does not exist, or update a resource item if the resource item exists. Note that a POST request with Upsert-Mode:false behaves as a POST without the custom header and performs the CREATE operation exclusively.
|
Prefer |
You can use this header to receive only those fields that are included in the compact view of the response payload. You can specify the value |
REST-Pretty-Print |
There is a reasonable formatting in REST response resulting in a lot of white space. You can use gzip to transport a zipped up response content. See ADF REST Payload Compression Support. However, the extracted content on the client would still contain the white spaces resulting in processing time on the clients that can be reduced considerably by using this header. See How to Control the Format of the ADF REST Response. |
Metadata-Context |
A metadata revision that indicates the MDS label to be used at runtime. A metadata revision is created at the end of an event that updates mainline metadata; for example, MDS MAR deployment or unified sandbox publishing. If your environment is unified sandbox enabled, you must use the sandbox property in the value, which is treated as the unified sandbox ID. The Metadata-Context header is honored only if the ApplSessionFilter is the first filter that initializes ADFContext. The mode for ADFSessionOptions is always set to EDIT when this header is present. If you specify a revision, ADFSessionOptions will be configured according to the metadata revision. If you want to execute the REST service in the context of a specific metadata revision, use the following syntax. This will ensure that the execution of REST service is isolated from other metadata changes happening in the application until the REST client is ready to consume those changes. Metadata-Context: revision="<metadata revision ID>" If you wan to test the REST services with changes in a sandbox, use the following syntax. Metadata-Context: sandbox="<unified sandbox ID>" |
ADF REST HTTP Method and Payload Support
The ADF REST framework supports operations on the following HTTP methods.
-
GET -
POST -
PATCH -
DELETE
GET Method Operations
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 or all available resources (when version identifier and resource collection are omitted).
http://server/demo/rest/[
{version}/{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 tables. All GET method URI parameters can be combined with any other parameter in the table, except where noted on the
expandandfieldparameters. 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 tables specify 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-10 Supported GET Method Query String Parameters Used Only in Resource Collections
| GET URI Parameter | Value | Description |
|---|---|---|
|
Starting in ADF REST framework version 2, |
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 a query parameter value has a special character (like ‘;’, ‘,’, ‘=’ or similar), then the value (in the expression) should be enclosed in quotes to define a literal value. If the literal value contains quotes, then, in addition, the quotes need to be escaped, as defined by the framework version, to be viable:
Additionally, in version 1, if the query parameter value contains a reserved word (such as
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 version 1, if the value contains both a special character and a reserved word, then the value needs to be enclosed in single quotes (
For examples 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 examples of rowmatch expressions, see What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2. |
|
|
An expression containing the primary key attribute value definition. Format: Example: Or: An expression containing information about the row finder and its finder attributes. Format: Example: If the finder attribute value contains any special character like ‘;’, ‘,’, ‘=’ (or similar), the value must be defined as a literal and enclosed in double quotes. For example: If the finder attribute value is a literal value (enclosed in double quotes) and the value contains double quotation marks
|
The resource collection will be queried using the provided primary key and attribute values definitions. Alternatively, the resource collection will be queried using the provided row finder and attribute definitions. Finders with parameters whose type does not belong to The list of available finders (primary key finder and row finder) is provided in the describe. Allowed special characters in framework version 1 and later:
For a primary key finder example, see Filtering a Resource Collection with Primary Key Values. For a row finder example, see Filtering a Resource Collection with a Row Finder. |
|
|
boolean Default: |
The resource collection representation will include the estimated row count when For an example, see Returning the Estimated Count of Resource Items. |
|
|
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. |
|
|
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. |
Table 22-11 Supported GET Method Query String Parameters Used in Resource Collections or Resource Items
| GET URI Parameter | Value | Description |
|---|---|---|
|
Starting in ADF REST framework version 3 and later, For more information, see What Happens at Runtime: Invoking an ADF REST Framework Version. |
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). |
|
|
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. |
|
Starting in ADF REST framework version 3 and later, For more information, see What Happens at Runtime: Invoking an ADF REST Framework Version. |
Display all children. Format: Display one or more child resource using a comma-separated 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. |
|
|
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 |
|
|
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. To perform case-insensitive sorting on a resource collection, the attribute list must follow this format, using either the
or
|
Sorts a resource collection based on its attributes. If the By default, the fetched collection will be sorted in a case sensitive way unless either the For an example, see Sorting a Resource Collection. |
|
|
A comma separated list of Example: |
When a resource item or a resource collection is requested and the Note the |
Table 22-12 Supported GET Method Query String Parameters Used in Resource Catalog Describe
| GET URI Parameter | Value | Description |
|---|---|---|
|
|
|
Use to retrieve the description of resources with or without all details. By default, the full catalog is retrieved, performing an exhaustive describe that returns the complete set of information for all resources, including nested children resources. The full catalog describe therefore includes the following sections of information for each resource: title, attributes, collection, item, annotations, children, and links Note that annotations must be defined by the ADF REST resource developer in the application and may not be present on the resource. You can improve the readability of a large catalog and retrieve a shallow catalog limited to the titles and links of parent resources (does not include children resources) by appending the URL parameter If you do not want any metadata in the response but only self links, you can append Optionally, additional parameters may be appended to the minimal describe request to include children resources and / or resource annotations, as explained for the query parameters For an example, see Retrieving a Minimal Catalog Describe. |
|
|
(default depends on whether full or minimal catalog is retrieved) |
Use to either exclude or include resource annotations, as specified in the application. The default depends on the
Note that annotations must be defined by the ADF REST resource developer in the application and may not be present on the resource. You cannot use this parameter with |
|
|
|
Use to retrieve the description of resources of a certain visibility, as declared in the application. This URL parameter values specify including only public resources ( For an example, see Retrieving the Catalog Describe Based on Resource Visibility Declaration. For information about how the application developer declares visibility in the resource definition, see How to Hide a Resource from the Catalog Describe. |
|
|
A comma separated list of resource collection names. Format: Example: |
Use to retrieve the description of the named resources to filter resources at the catalog level. |
Table 22-13 Supported GET Method Query String Parameters Used in Resource Catalog Describe or Resource Item Describe
| GET URI Parameter | Value | Description |
|---|---|---|
|
|
(default depends on whether full or minimal catalog is retrieved) |
Use to either exclude or include all available children resources nested within a parent resource. The default depends on the
You cannot use this parameter with For a resource catalog describe example, see Retrieving a Minimal Catalog Describe. When a resource item describe is requested and |
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-14 Operators Supported by Data Types in Query (q) Parameter Strings
| ADF REST Data Type | Supported Operator |
|---|---|
|
integer |
|
|
number |
|
|
string |
|
|
date |
|
|
time |
|
|
datetime Note: Both UTC and local datetime formats are supported. The value returned is determined by the time zone configured for the VM. |
|
|
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
POST Method Operations
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} -
Create a parent resource item and create the nested child resource collection in one roundtrip.
http://server/demo/rest/
{version}/{resourceCollectionPath} -
Updating or creating resource items using Upsert-Mode Header
http://server/demoapp/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.resourceitem+json: When updating or creating a resource item using Upsert. -
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.resourceitem+json: When updating or creating a resource item using Upsert. -
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
PATCH Method Operations
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