Consuming ADF RESTful Web Services

About the ADF REST Framework

ADF provides a REST framework that supports creating and interacting with resources and ADF RESTful web services based on ADF Business Components. ADF REST framework supports the exchange of resource information by client and server during runtime.

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-Override header 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-Mode set 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.xml file for the application.
Declaring a default ADF REST framework version for individual REST resources to ensure the ADF REST runtime executes requests using functionality offered by a particular ADF REST framework version. Declaring a particular framework version allows service clients to opt into framework enhancements made by Oracle in subsequent releases of Oracle JDeveloper. The default ADF REST framework version is declared in the adf-config.xml file for the application. In JDeveloper 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

With RESTful web services, ADF Business Components view objects are represented as a resource collection when the RESTful web service is invoked at runtime.

ADF REST resources that service developers create in the ADF Business Components model project are based on view object instances that the project application module defines. For example:

A Departments resource is based on a DepartmentsVO view instance and its accessor to an EmployeesVO view instance.
An Employees resource is based on an EmployeesVO view instance.

At runtime, when an action of the RESTful web service is invoked, the payload returned by the service contains one or more resource collections, comprised of the row sets queried by the backing view objects and the individual attributes of the view object rows. The resource collections preserve the relationship of master-detail coordinating view instances.

As Table 22-1 shows, the resource collection is the RESTful web service payload representation of a view object instance. The resource items are the rows and attributes of the payload item object, which in turn correspond to view object rows.

Note:

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

Table 22-1 JSON Objects and ADF Business Component Representation

JSON Object	ADF Business Component
`resource collection`	View object instance comprised of one or more rows. `Departments`, `Employees` are examples of resource collections based on `DepartmentsVO` and `EmployeesVO` view instances.
`resource item`	A view object row. The specific department `10` or employee `1012` are examples of resource items from the `Departments` and `Employees` resource collections.

Retrieving the ADF REST Catalog Describe

When you invoke an HTTP GET method in RESTful web service to describe all the available resources in the resource catalog, it returns JSON objects that contain the attributes, actions, and links defined in the REST resource definitions for the web service.

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/describe

Note:

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=minimal

Additionally, 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=true

The 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
`metadataMode`	`verbose` (default) `minimal` `list`	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 `?metadataMode=minimal` to the describe request. If you do not want any metadata in the response but only self links, you can append `?metadataMode=list` to the describe request. 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 `showAnnotations` and `includeChildren`. For example, you can append `?metadataMode=minimal&includeChildren=true` to retrieve a minimal catalog describe with all children resources included.
`showAnnotations`	`true`, `false` (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: By default, a full catalog (`metadataMode=verbose`) describe includes annotations. To exclude resource annotations from the full catalog describe, you can append `?showAnnotations=false` on the describe request. By default, a minimal catalog (`metadataMode=minimal`) describe excludes annotations. To include resource annotations in the minimal catalog describe, you can append `?showAnnotations=true` on the describe request. 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 `?metadataMode=list`.
`includeChildren`	`true`, `false` (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: By default, a full catalog (`metadataMode=verbose`) describe includes all children resources. To exclude children resources from the full catalog describe, you can append `?includeChildren=false` on the describe request. By default, a minimal catalog (`metadataMode=minimal`) describe excludes all children resources. To include children resources in the minimal catalog describe, you can append `?includeChildren=true` on the describe request. You cannot use this parameter with `?metadataMode=list`.
`include`	`public` (default), `unlisted`, `all`	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 (`public`), only private resources (`unlisted`), or both types (`all`). By default, only resources that are public are shown in the describe. To view private resources, you must append either `?include=all` or `?include=unlisted` on the describe request. See How to Hide a Resource from the Catalog Describe.
`resources`	A comma separated list of resource collection names. Format:`<resName1>,<resName2>` Example: `?resources=Departments,Employees`	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 children attribute identifies nested resources.
Examine these resource objects to understand the shape of each resource:
- attributes specifies the list of available resource collection attributes.
- collection specifies the shape of the collection and specifies finders for row finder, links, and available actions (including media types).
- item specifies the shape of the instances of the collection and itself specifies links and available actions.
- children specifies any nested resources (and itself contains attributes, collection, and item objects).

For example, the describe for 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 the include 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=true

The 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=all or ?include=unlisted and 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

When you invoke an HTTP GET method in RESTful web service to describe a single resource, all the available resources, or the nested resources, it returns a JSON object that contains the attributes, actions, and links defined in the REST resource definition.

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:
- attributes specifies the list of available resource collection attributes.
- collection specifies the shape of the collection and specifies finder for row finder, links, and available actions (including media types).
- item specifies the shape of the instances of the collection and itself specifies links and available actions.
- children specifies any nested resources (and itself contains attributes, collection, and item objects).

For example, the describe for the Departments resource returns the following objects:

{
  "Resources" : {
    "Departments" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      } ],
      "collection" : {
        ...
        } ],
        "finders" : [ {
        } ]
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "item" : {
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "children" : {
        "Employees"
          ...
        } ],
      ...
      "links" : [ {
      } ]
  }
}

The following sample describes version 11.0 of the Departments resource.

Request

URL

http://server/demo/rest/11.0/Departments/describe
HTTP Method

GET
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.description+json

Payload

{
  "Resources" : {
    "Departments" : {
      "discrColumnType" : false,
      "attributes" : [ {
        "name" : "DepartmentId",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 4
      }, {
        "name" : "DepartmentName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 30
      }, {
        "name" : "RelState",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true
      } ],
      "collection" : {
        "rangeSize" : 25,
        "finders" : [ {
          "name" : "PrimaryKey",
          "attributes" : [ {
            "name" : "DepartmentId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 4
          } ]
        } ],
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments",
          "name" : "self",
          "kind" : "collection"
        } ],
        "actions" : [ {
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
        }, {
          "name" : "create",
          "method" : "POST",
          "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "testImpl",
          "parameters" : [ {
            "name" : "testid",
            "type" : "string",
            "mandatory" : false
          } ],
          "resultType" : "string",
          "method" : "POST",
          "requestType" : [ "application/vnd.oracle.adf.action+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
        } ]
      },
      "item" : {
        "links" : [ {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees",
          "name" : "Employees",
          "kind" : "collection",
          "cardinality" : {
            "value" : "1 to *",
            "sourceAttributes" : "DepartmentId",
            "destinationAttributes" : "DepartmentId"
          }
        }, {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/{id}",
          "name" : "self",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/{id}",
          "name" : "canonical",
          "kind" : "item"
        } ],
        "actions" : [ {
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "update",
          "method" : "PATCH",
          "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "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 children attribute identifies nested resources.
Examine the resource item describe to understand its shape.
- attributes specifies the list of available resource collection attributes.
- item specifies links to the item, including defined child collections, and available actions.
- links specifies describe links.

For example, the describe for a Departments resource item returns the following objects:

{
  "Resources" : {
    "Departments" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      } ],
      "item" : {
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "links" : [ {
      } ]
  }
}

The following sample describes version 11.0 of an instance of the Departments resource collection.

Note: To recursively include all children of the resource item on the requested describe, provide the query parameter ?includeChildren=true on the describe URL.

Request

URL

http://server/demo/rest/11.0/Departments/10/describe
HTTP Method

GET
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.description+json

Payload

{
  "Resources" : {
    "Departments" : {
      "discrColumnType" : false,
      "attributes" : [ {
        "name" : "DepartmentId",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 4
      }, {
        "name" : "DepartmentName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 30
      }, {
        "name" : "RelState",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true
      } ],
      "item" : {
        "links" : [ {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
          "name" : "Employees",
          "kind" : "collection",
          "cardinality" : {
            "value" : "1 to *",
            "sourceAttributes" : "DepartmentId",
            "destinationAttributes" : "DepartmentId"
          }
        }, {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "self",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "canonical",
          "kind" : "item"
        } ],
        "actions" : [ {
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "update",
          "method" : "PATCH",
          "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
          "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
        }, {
          "name" : "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 children attribute identifies nested resources.
Examine these resource objects to understand the shape of each resource:
- attributes specifies the list of available resource collection attributes.
- collection specifies the shape of the collection and specifies finder for row finder, links, and available actions (including media types).
- item specifies the shape of the instances of the collection and itself specifies links and available actions.
- children specifies the nested resources (and itself contains attributes, collection, and item objects).

For example, the describe for the nested resources Departments and Employees returns the following objects:

{
  "Resources" : {
    "Employees" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      } ],
      "collection" : {
        ...
        } ],
        "finders" : [ {
        } ]
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "item" : {
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "children" : {
        "Departments"
          ...
        } ],
      ...
      "links" : [ {
      } ]
  }
}

The following sample (URL1) describes version 11.0 of the Employees resource which can be found in the context of a Department. The second sample (URL2), describes an item of the same nested resource Employees, where the ID of the employee identifies the nested resource item.

Note: To recursively include all children of the resource item on the requested describe, provide the query parameter ?includeChildren=true on the describe URL.

Requests

URL 1

http://server/demo/rest/11.0/Departments/10/child/Employees/describe
URL 2

http://server/demo/rest/11.0/Departments/10/child/Employees/200/describe
HTTP Method

GET
Content-Type

none
Payload

none

Responses

HTTP Code

200
Content-Type

application/vnd.oracle.adf.description+json

Payload 1

{
  "Resources" : {
    "Employees" : {
      "discrColumnType" : false,
      "attributes" : [ {
        "name" : "EmployeeId",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 6
      }, {
        "name" : "FirstName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true,
        "precision" : 20
      }, {
        "name" : "LastName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 25
      }, {
        "name" : "Email",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 25
      }, {
        "name" : "JobId",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 10,
        "controlType" : "choice",
        "maxLength" : "10",
        "lov" : {
          "childRef" : "JobsLOV",
          "attributeMap" : [ {
            "source" : "JobTitle",
            "target" : "JobId"
          } ],
          "displayAttributes" : [ "JobTitle" ]
        }
      }, {
        "name" : "DepartmentId",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true,
        "precision" : 4
      }, {
        "name" : "Salary",
        "type" : "number",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true,
        "precision" : 8,
        "scale" : 2
      }, {
        "name" : "Picture",
        "type" : "attachment",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : false,
        "actions" : [ {
          "name" : "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 resources query parameter.
Locate the names of the resources in the describe.
Examine these resource objects to understand the shape of each resource:
- attributes specifies the list of available resource collection attributes.
- collection specifies the shape of the collection and specifies finders for row finder, links, and available actions (including media types).
- item specifies the shape of the instances of the collection and itself specifies links and available actions.
- children specifies any nested resources (and itself contains attributes, collection, and item objects).

For example, the describe for the Departments resource returns the following objects:

{
  "Resources" : {
    "Departments" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      } ],
      "collection" : {
        ...
        } ],
        "finders" : [ {
        } ]
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "item" : {
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "children" : {
        "Employees"
          ...
        } ],
      ...
      "links" : [ {
      } ]
  }
}

The following sample 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 partialDescription parameter 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 children element to identify the partial describe link for the next child resource in the resource hierarchy (to a depth of one nested resource).
- attributes specifies the list of available resource collection attributes.
- collection specifies the shape of the collection and specifies finder for row finder, links, and available actions (including media types).
- item specifies the shape of the instances of the collection and itself specifies links and available actions.
- children identifies any nested resource to a depth of one object and contains a describe link with the ?partialDescription parameter to retrieve its partial description (this child resource describe specifically does not contain the attributes, collection, and item objects).

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:
- attributes specifies the list of available resource collection attributes.
- collection specifies the shape of the collection and specifies finder for row finder, links, and available actions (including media types).
- item specifies the shape of the instances of the collection and itself specifies links and available actions.
- children specifies any nested resources (and itself contains attributes, collection, and item objects).

For example, the describe for the Departments resource returns the following objects:

{
  "Resources" : {
    "Departments" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      } ],
      "collection" : {
        ...
        } ],
        "finders" : [ {
        } ]
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "item" : {
        "links" : [ {
        } ]
        "actions" : [ {
        } ]
      },
      "children" : {
        "Employees"
          ...
        } ],
      ...
      "links" : [ {
      } ]
  }
}

The following 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=DepartmentName

URL 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 ADF, you can create version identifiers for an ADF REST resource and assign lifecycle status so that you can manage and update an existing resource definition with ease.

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:
- version specifies the version name, as defined in the adf-config.xml file.
- isLatest property specifies the version name of the most recent release version.
- predecessor-version specifies the link to the previous release version.
- successor-version specifies the link to the next latest release version.
- current specifies 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:
- defaultFrameworkVersion property 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 the adf-config.xml file. 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.
- allowedFrameworkVersions property 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 the REST-Framework-Version header.

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 GET method on REST resources to retrieve a resource or nested resource, page a resource, filter a resource collection with a query, or sort a resource collection.

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 @context element.

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 finders attribute in the collection element. The name attribute identifies the finder as PrimaryKey. Also locate the name of the primary key attributes under attributes.
Execute a GET with the query parameter finder and pass the primary key attributes using the finder name PrimaryKey.

For example, the Employees resources describe returns the following:

"collection" : {
     "rangeSize" : 24,
     "finders" : [ {
       "name" : "PrimaryKey",
       "attributes" : [ {
         "name" : "EmployeeId",
         "type" : "integer",
         "updatable" : true,
         "mandatory" : true,
         "queryable" : false
         "precision" : 4,
} ]

The following sample fetches the Employees collection specified by the finder PrimaryKey where the EmployeeId attribute value 101 is passed.

Note: To filter the collection by a non-primary key attribute, see Filtering a Resource Collection with a Row Finder.

Request

URL

http://server/demo/rest/11.1/Employees?finder=PrimaryKey;EmployeeId=101
HTTP Method

GET
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload

{
  "items" : [ {
    "EmployeeId" : 101,
    "FirstName" : "Neena",
    "LastName" : "Smith",
    "Email" : "NSMITH",
    "JobId" : "AD_VP",
    "DepartmentId" : 90,
    "Salary" : 2000,
    "links" : [ {
      "rel" : "self",
      "href" : "http://server/demo/rest/11.1/Employees/101",
      "name" : "Employees",
      "kind" : "item"
    }, {
      "rel" : "canonical",
      "href" : "http://server/demo/rest/11.1/Employees/101",
      "name" : "Employees",
      "kind" : "item"
    } ]
  } ],
  "count" : 1,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "http://server/demo/rest/11.1/Employees",
    "name" : "Employees",
    "kind" : "collection"
  } ]
}

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 @context section 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 key element appears within the @context section and contains the unique identifier of the specific resource item as a string.
The links section within the @context section no longer list any properties, like changeIndicator.
The changeIndicator value is moved to ETag, which is under a headers element within the @context section.

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 HTTP POST method to create a resource and child resource item in the REST resource collection.

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 the HTTP PATCH method to update a resource in the REST resource collection.

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 the HTTP DELETE method to delete a resource in the REST resource collection.

The ADF REST runtime supports deleting resource items using a DELETE method. The framework does not currently support deleting a resource collection.

The following sample (URL1) deletes employee ID 99999 of the Employees resource collection as a child of the Departments resource item 17. The second request URL deletes the Departments resource item 17.

Request

URL 1

http://server/demo/rest/11.0/Departments/17/child/Employees/99999
URL 2

http://server/demo/rest/11.0/Departments/17
HTTP Method

DELETE
Content-Type

none
Payload

none

Response

HTTP Code

204
Content-Type

none
Payload

none

Checking for Data Consistency

When updating or retrieving ADF REST resource items using the HTTP method, you can check data consistency by generating an entity tag with precondition headers so that the resource item matches the server side resource state before updating or retrieving.

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 changeIndicator property in the properties section 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 the properties section.

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 changeIndicator property in the properties section 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 properties section. In the case of framework versions 6 and later, the ETag for each of the items will be in the @context element 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

304 state not modified
Content-Type

none
Payload 1

none

Request 2

URL 2

http://server/demo/rest/11.0/Departments/10
HTTP Method

GET
Precondition 2

If-None-Match: "unmatchedETagXYZ"
Content-Type

none
Payload

none

Response 2

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json
ETag

responseETag123

Payload 2 (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 of custom content that is not contained in the payload by using a link to the content. You can create LOB content at the same time that you are creating or retrieving a resource item using the HTTP methods.

The ADF REST runtime supports content streaming for BLOB or CLOB attributes.

LOB attributes may be handled in the following ways.

Linked to as custom content that is not contained in the payload itself.

This is the default for BLOB and CLOB attributes and specified in the response payload using the enclosure link type to point to a resource that cannot be represented with the supported payload types (such as image/png).
Encoded into Base64 string format and contained in the request payload itself.

Currently, advanced features (like support for Chunked encoding) are not supported by the ADF REST runtime. Developers working on an enterprise architecture, may wish to investigate the use of specialized content management systems (such as Oracle WebCenter Content).

Instead of showing the LOB attribute in the attribute section, the response payload always contains an enclosure link to the content. The following describe for an Employees resource item defines the BLOB attribute Picture with a default requestType of application/octet-stream. The enclosure link for the resource item appears in the items section. The actions section identifies the operations that may be used to manipulate the content.

{
  "Resources" : {
    "Employees" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
      }, {
        "name" : "Picture",
        "type" : "attachment",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : false,
        "actions" : [ {
          "name" : "delete",
          "method" : "DELETE"
        }, {
          "name" : "get",
          "method" : "GET",
          "responseType" : [ "application/octet-stream" ]
        } ]
      } ],
      "item" : {
        "links" : [ {
         ...
        }, {
          "rel" : "enclosure",
          "href" : "http://server/demo/rest/11.0/Employees/101/enclosure/Picture",
          "name" : "Picture",
          "kind" : "other"
        } ],
        "actions" : [ {
        } ]
      },
      "links" : [ {
        ...
      } ]
  }
}

The attribute content type of the resource item can be assigned by the ADF REST resource developer by configuring the contentType property as a custom property of the LOB-type attribute. For example, when working with PNG image files, the following content type can assigned in advance:

Custom Property: contentType
Value: image/png

In some use cases the attribute value itself is a link to some external content. When an attribute is configured this way, it is not only shown in the resource item payload but a link that points to the external content is also created. In the resource description, only the GET action will be available for the external link. You can modify the URL contained in the attribute value by making a request with an update on the resource item.

An attribute can be configured by the ADF REST resource developer to generate a link by adding the following attribute:

Name: inputHandler
Value: oracle.adf.internal.model.rest.core.binding.inputHandler.LinkInputHandler

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 enclosure link for the desired attribute. The item section defines the available links for the attribute.

Alternatively, you can execute the resource describe to identify the enclosure link generated for resource items. In general, the resource describe contains other useful information not returned in the GET response payload, including the expected response type (image/png, for example) and supported actions for the attribute.
Execute an HTTP operation (GET or DELETE) using the link to the LOB content.

The following resource item for Employees 101 shows the enclosure link for the Picture attribute in the links section.

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

In ADF, you can retrieve LOV-enabled attributes when you create or retrieve existing resource items using the HTTP methods. The ADF REST runtime supports retrieving LOV-enabled attribute values when the resource item does not exist in the resource collection.

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 lov description of a resource attribute, locate the childRef property to identify the child resource collection that contains the LOV choices. Note that the resource describe of a LOV child resource does not show the lov description, as the operation to retrieve LOV-enabled attribute values is not supported on LOV child resources.

The lov description contains the view object attribute mapping from the resource item to the LOV child resource collection. The attribute mapping contains one or more source attributes from the child resource whose values will be copied to the resource item when an LOV value is selected. An LOV selection could derive more values in the resource item besides the attribute displaying the LOV. In such cases, the attribute mapping will identify it as derived = true. Finally, the lov description identifies which attributes from the child resource collection could be used for displaying to end users if the results are bound to a user interface.
Then, look for the resource item links element and locate the link with a rel of lov and the href that identifies the corresponding LOV child resource (as specified in the resource item childRef property).

Tip: The resource describe displays the LOV child resource as a template that is completed by supplying a specific resource item name from the resource collection. You may execute a GET to retrieve the resource collection and locate the working link for the LOV child resource that corresponds to the specific resource item.
Execute a GET using the LOV link and, optionally, use additional filtering to narrow down the LOV results or to exclude not needed attributes from the payload. You should always fetch the display attributes listed in the lov description. The display attribute is the attribute value that allows the end user to make an LOV value selection from a list of values that they would recognize (such as the list of job titles). The LOV definition ensures that the correct source attribute is used to update the resource item when the LOV selection is applied.

For example, the Employees resource collection describe returns the following:

{
  "Resources" : {
    "Employees" : {
      "discrColumnType" : false,
      "attributes" : [ {
        "name" : "EmployeeId",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 6
      }, {
        "name" : "FirstName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true,
        "precision" : 20
      }, {
        "name" : "LastName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 25
      }, {
        "name" : "Email",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 25
      }, {
        "name" : "JobId",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 10,
        "controlType" : "choice",
        "maxLength" : "10",
        "lov" : {
          "childRef" : "JobsLOV",
          "attributeMap" : [ {
            "source" : "JobId",
            "target" : "JobId"
          } ],
          "displayAttributes" : [ "JobTitle" ]
        }
     ...

      "item" : {
        "links" : [ {
          "rel" : "lov",
          "href" :
                  "http://server/demo/rest/11.0/Employees/{id}/lov/JobsLOV",
          "name" : "JobsLOV",
          "kind" : "collection"
        }, {
...

The following sample fetches the values for the LOV display attribute JobTitle from the JobsLOV resource collection. The query parameters onlyData and fields ensure the representation is filtered to contain only data in the response payload, where President and Administration Assistant are examples of the values of the display attribute JobTitle.

Request 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 lov description of an attribute, locate the lovResourcePath property to identify the LOV resource that contains the LOV choices. Note that the resource describe of a LOV child resource does not show the lov description, as the operation to retrieve LOV-enabled attribute values is not supported on LOV child resources.

The lov description contains the attribute mapping from the resource item to the LOV resource collection. The attribute mapping contains one or more source attributes from the LOV resource whose values will be copied to the resource item when an LOV value is selected. An LOV selection could derive more values in the resource item besides the attribute displaying the LOV. In such cases, the attribute mapping will identify it as derived = true. Finally, the lov description identifies which attributes from the LOV resource collection could be used for displaying to end users if the results are bound to a user interface.
Then, look for the resource collection describe links element and locate the link with a rel of lov and the href that identifies the LOV resource (as specified in the lovResourcePath property).

Note the lovResourcePath is an array that may specify more than one LOV resource. The array supports the use case of dependent LOV-enabled attributes (also called cascading LOVs). For example, the array "lovResourcePath" : [ "Countries", "States" ] identifies LOV resources Countries and States, where the LOV list to display the states is dependent on the LOV selection for countries. To get the values to display for the dependent LOV attribute, you use a child link from the parent LOV resource collection as follows:
1. Execute a GET using the LOV resource link (where rel: lov and name: Countries).
2. The end user selects a resource item from the LOV resource collection (for example, United States).
3. Execute a GET using the child link (rel: child and name: States) in the selected resource item. This will retrieve a resource collection with the list of values (states) based on the parent LOV resource (countries).
Execute a GET using the LOV resource link and, optionally, use additional filtering to narrow down the LOV results or to exclude not needed attributes from the payload. You should always fetch the display attributes listed in the lov description. The display attribute is the attribute value that allows the end user to make an LOV value selection from a list of values that they would recognize (such as the list of job titles).
With the cached LOV attribute values from the LOV resource, it is then possible to display the LOV display attribute in the client user interface where the end user is expected to enter values to create a new resource item. When enters the desired values, chooses a value from the displayed LOV for the LOV-enabled attribute, and then clicks Submit, the client can execute the create request. The ADF Business Components view object attribute's LOV definition ensures that the correct source attribute is used to update the resource item when the LOV selection is applied. For details about submitting a POST request with the payload that creates a new resource item, see Creating a Resource Item in Collection.

For example, the Employees resource collection describe returns the following:

{
  "Resources" : {
    "Employees" : {
      "discrColumnType" : false,
      "attributes" : [ {
        "name" : "EmployeeId",
        "type" : "integer",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 6
      }, {
        "name" : "FirstName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : false,
        "queryable" : true,
        "precision" : 20
      }, {
        "name" : "LastName",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 25
      }, {
        "name" : "Email",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 25
      }, {
        "name" : "JobId",
        "type" : "string",
        "updatable" : true,
        "mandatory" : true,
        "queryable" : true,
        "precision" : 10,
        "controlType" : "choice",
        "maxLength" : "10",
        "lov" : {
          "childRef" : "JobsLOV",
          "attributeMap" : [ {
            "source" : "JobId",
            "target" : "JobId"
          } ],
          "displayAttributes" : [ "JobTitle" ],
          "lovResourcePath" : [ "Jobs" ]
        }
      ...
      },
      "links" : [ {
        ...
          "rel" : "lov",
          "href" : "http://server/demo/rest/11.0/Jobs",
          "name" : "Jobs",
          "kind" : "collection"
        }, {
...

The following sample fetches the values for the LOV display attribute JobTitle from the Jobs resource collection. The query parameters onlyData and fields ensure the representation is filtered to contain only data in the response payload, where President and Administration Assistant are examples of the values of the display attribute JobTitle.

Request 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 lov description of an attribute, locate the childRefForCreate property to identify the LOV resource that contains the LOV choices.

The lov description contains the attribute mapping from the resource item to the LOV resource collection. The attribute mapping contains one or more source attributes from the LOV resource whose values will be copied to the resource item when an LOV value is selected. An LOV selection could derive more values in the resource item besides the attribute displaying the LOV. In such cases, the attribute mapping will identify it as derived = true. Finally, the lov description identifies which attributes from the LOV resource collection could be used for displaying to end users if the results are bound to a user interface.
Then, look for the resource item describe links element and locate the link with a rel of lov and the href for 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 lov description. The display attribute is the attribute value that allows the end user to make an LOV value selection from a list of values that they would recognize (such as the list of 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 childRefForCreate property) with parametrized row finder for the selected resource item. Execute a GET using the LOV resource link (rel: lov and name: 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 the adf-config.xml file.
- When a request specifies a framework version, the specified framework version will be honored.

Service clients may pass the custom header REST-Framework-Version on the REST resource request to specify the framework version to use to execute the request. The ADF REST framework version passed in the version header overrides the default framework declaration defined by the application in the adf-config.xml file by the REST service developer.

When the service client passes no version header in the request, the ADF REST runtime uses the default, as defined in the adf-config.xml file. When a default framework version is not defined and no version header is passed, then the base version (version 1) of the ADF REST framework is assumed.

The framework version declaration is made by ADF REST resource developers in the adf-config.xml file for each application-specific resource version name. For example, the sample following shows resource versions 11.2, 11.1, and 11.0 with the framework versions 3, 2, and 1 declared.

<versions>
    <version name="11.2" displayName="11.2" restFrameworkVersion="2"/>
    <version name="11.1" displayName="11.1" lifecycle="deprecated" restFrameworkVersion="1"/>
    <version name="11.0" displayName="11.0" lifecycle="deprecated" restFrameworkVersion="1"/>
</versions>

In the above example, when the request does not pass a framework version header, resources 11.0 and 11.1 will use the old payload format, while 11.2 will use the new payload format. This ensures, in cases where a framework version is not specified in the request, existing service clients which access resources for a particular release will not be affected when the ADF REST framework introduces a new payload format; yet new service clients which access the latest resources may pick up the new payload format.

For the root resource /context, the default ADF REST framework version for the latest release will be used.

The service client may want to find out the default framework version for a particular release. To support this use case, ADF REST will return the default framework version in the resource version describe, as the following sample shows. 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 version property to identify the release version.
Examine the associated defaultFrameworkVersion property to understand the version of the ADF REST framework that will be used to execute requests for the specific release version:
- defaultFrameworkVersion property 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 the adf-config.xml file. 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 allowedFrameworkVersions property to understand what versions that you may use:
- allowedFrameworkVersions property 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 the REST-Framework-Version header.

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

The exception detail payload will be generated for an ADF REST error response when the following conditions exist:

ADF REST framework version is version 4.
Either application/vnd.oracle.adf.error+json or application/json is 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

You can use the HTTP methods at ADF REST runtime to perform advanced operations such as fetching a resource collection with a row finder, obtaining a count of resource items in a resource collection, querying a resource with a filter, and retrieving LOV attribute values for an existing resource item.

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 finders attribute in the collection element. The name attribute identifies the row finder definition name. Also locate the name of the row finder parameter under attributes.
Execute a GET with the query parameter finder and pass the row finder name and parameters.

For example, the Departments resources describe returns the following:

"collection" : {
     "rangeSize" : 25,
     "finders" : [ {
       "name" : "EmpByEmailFinder",
       "title" : "EmployeesByEmailVC",
       "attributes" : [ {
         "name" : "Email",
         "type" : "string",
         "updatable" : true,
         "required" : "Optional",
         "queryable" : false
} ]

The following sample fetches the Departments collection specified by a row finder EmpByEmailFinder where the Email attribute value NSMITH is passed.

Request

URL

http://server/demo/rest/11.1/Employees?finder=EmpByNameFinder;Email=NSMITH
HTTP Method

GET
Content-Type

none
Payload

none

Response

HTTP Code

200
Content-Type

application/vnd.oracle.adf.resourceitem+json

Payload

{
  "items" : [ {
    "EmployeeId" : 101,
    "FirstName" : "Neena",
    "LastName" : "Smith",
    "Email" : "NSMITH",
    "JobId" : "AD_VP",
    "DepartmentId" : 90,
    "Salary" : 2000,
    "links" : [ {
      "rel" : "self",
      "href" : "http://server/demo/rest/11.1/Employees/101",
      "name" : "Employees",
      "kind" : "item"
    }, {
      "rel" : "canonical",
      "href" : "http://server/demo/rest/11.1/Employees/101",
      "name" : "Employees",
      "kind" : "item"
    }, {
      "rel" : "lov",
      "href" : "http://server/demo/rest/11.1/Employees/101/lov/JobsLOV",
      "name" : "JobsLOV",
      "kind" : "collection"
    } ]
  } ],
  "count" : 1,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "http://server/demo/rest/11.1/Employees",
    "name" : "Employees",
    "kind" : "collection"
  } ]
}

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

ADF REST framework supports encoding of HTTP payloads, different media types, HTTP headers, and methods, so that the communication between the server and client is seamless and secure.

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
`self`	Always generated for a resource. The `href` points to the resource itself or to the resource describe. In the `links` object, the link name is `self` for this `rel`.
`canonical`	Always generated. The `href` points to the canonical resource or to the canonical resource describe. If a canonical resource is not defined, it will have the same `href` that `self` has. In the `links` object, the link name is `canonical` for this `rel`.
`parent`	Always generated for a nested resource. The `href` points to the `self` link of the parent resource. In the `links` object, the link name is `parent` for this `rel`.
`child`	Generated when the resource has nested children. The `href` points to the nested collection. In the `links` object, the link name is the accessor name for this `rel`.
`lov`	Generated on a resource item for LOV-enabled (list of values) attributes. There are two types of `href`: 1.) on the `links` object of the resource item, the `href` identifies an LOV child resource (name specified in the `childRef` property of the resource item), and 2.) on the `links` object of the resource describe, the `href` identifies a LOV resource (name specified in the `lovResourcePath` property on the resource item). 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.
`enclosure`	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 `enclosure` link (can be obtained from resource item `describe`, `get`, or `post`/`patch` response) to read/update/delete content.
`external`	Generated for a resource that exists outside of the framework domain.
`current`	Generated in the resource version describe when multiple resource version identifiers exist. The `href` points to the most recent version identifier, as defined by the `adf-config.xml` version definition.
`predecessor-version`	Generated in the resource version describe when multiple resource version identifiers exist. The `href` points to the previous version identifier, as defined by the `adf-config.xml` version definition.
`successor-version`	Generated in the resource version describe when multiple resource version identifiers exist. The `href` points to the next most recent version identifier, as defined by the `adf-config.xml` version definition.
`describe`	Generated in the resource version describe. The `href` points to the resource catalog describe for all resources of the same version.

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 `q` query parameter is limited to a query-by-example.		`GET /rest/19.0/Departments?q=Dname SA*;Loc BOSTON`
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 `q` query parameter value differently than Framework version 1. Supports filtering resource collections using `rowmatch` query expressions.	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 `GET` operations to use the `?expand` and `?fields` query parameter to return a nested child resource as a resource collection with the `hasMore` attribute	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 `application/vnd.oracle.adf.error+json` or `application/json` media types.	Supports the response in the form an exception detail payload that provides the following benefits to the web application: Presents the details of each error in a hierarchical structure if multiple errors occur in a single request. Identifies the exception corresponding to each error by including an application specific error code. Presents an error path that identifies the location of each error in the request payload structure.	The exception detail may or may not present certain details, such as the application-specific error code and the request payload’s error path.	See Obtaining an Exception Payload Error Response.
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.	`GET /rest/v1/Cities?finder=ByStateFinder;stateName={State}",` See What You May Need to Know About Configuring LOV Resources for Row Finders. The supported Java types include `java.util.List` and `java.util.Map`.
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 `links` and `headers` appear within `@context` field in resource item response object `links` field in `@context` will no longer have the `properties` field. `headers -> ETag` has the `changeIndicator` value. `key` field under `@context` contains the unique identifier of the specific resource item as a string. `warnings` field under `@context` contains the validation error details when a validation rule has been enabled on a backing entity object attribute.		... "@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
`identity`	Does not compress the payload. The behavior is the same as when the encoding is omitted.
`x-gzip` and `gzip`	Compresses the payload using the format produced by the file compression program `gzip` (GNU zip), as described in RFC 1952 [25]. This format is a `Lempel-Ziv` coding (LZ77) with a 32 bit CRC.
`deflate`	Compresses the payload with a combination of the `zlib` format defined in FRC 1950 [31] and the `deflate` compression mechanism described in RFC 1951 [29].

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
`application/vnd.oracle.adf.resourcecollection+json`	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 `items` attribute is based on the resource definition. For an example, see Describing a Resource Collection.
`application/vnd.oracle.adf.resourceitem+json`	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 `links` is automatically generated by the framework. All the other attributes are based on the resource definition. For an example, see Describing a Resource Item.
`application/vnd.oracle.adf.actionresult+json`	POST method	Describes the result of an action execution.
`application/vnd.oracle.adf.description+json`	GET method	Describes the resource and its elements. For an example, see Describing All Available Resources.
		.
`application/vnd.oracle.adf.batch+json`	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.
`application/vnd.oracle.adf.version+json`	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.
`application/vnd.oracle.adf.error+json`	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: `oracle.jbo.valuemaps.Boolean10PropertySet` `oracle.jbo.valuemaps.BooleanTFPropertySet` `oracle.jbo.valuemaps.BooleanYNPropertySet`	`boolean`
Java Class: `oracle.jbo.domain.ClobDomain` or `oracle.jbo.domain.BlobDomain`	`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`	`date` if Java type is `java.sql.Date` `time` if Java type is `java.sql.Time` `datetime` if Java type is other (not `java.sql.Date` and not `java.sql.Time`) The REST service accepts the `YYYY-MM-DDThh:mm:ss.s+hh:mm` or `YYYY-MM-DDThh:mm:ss.s-hh:mm` format. If you specify the time without the “:” in the second part, `s+hhmm` or `s-hhmm`, it fails.

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
`200 OK`	Request successfully executed and the response has content.
`201 Created`	Resource successfully created. The response contains the created resource.
`204 No Content`	Request successfully executed and the response doesn't have content.
`304 Not Modified`	According to the provided ETag, the resource was not modified.
`400 Bad Request`	The request could not be understood by the server due to malformed syntax.
`401 Unauthorized`	The server is refusing to service the request because the resource of the request is secured and authentication has not yet been provided.
`404 Not Found`	The requested resource was not found.
`406 Not Acceptable`	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.
`412 Precondition failed`	The resource state in the server side doesn't match the provided ETag.
`415 Unsupported Media Type`	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.
`500 Internal Server Error`	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
`Content-Type`	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.
`Content-Encoding`	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.
`Accept`	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.
`Accept-Encoding`	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.
`REST-Framework-Version`	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 `adf-config.xml` file, as described in Working with ADF REST Framework Versions.
`Location`	Use to identify the URI of a newly created resource. The ADF REST framework includes the `Location` header in the response of a POST to create a new resource. For an example, see Creating a Resource Item in Collection.
`ETag`	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 `ETag` generation for resources backed by an ADF Business Components entity object that has been configured to use an change-indicator attribute. See Checking for Data Consistency.
`If-Match`	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.
`If-None-Match`	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.
`X-HTTP-Method-Override`	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.
`X-Requested-By`	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 `enableAntiCSRF` ResourceServlet init parameter to `True`. This header is not enforced if the GET, OPTIONS, and HEAD methods are used. If the header cannot be found, then 400 (Bad Request) is returned.
`Cache-Control`	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: `no-cache`, `no-store`, `must-revalidate`. 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, `Cache-Control` can be configured only as `<MaxAge>` `<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 `<MaxAge>` is used to create the `Cache-Control` string like `max-age=30` to specify the resource will be considered fresh for thirty seconds. This value is also set in the `Cache-Control` header in the response for an operation involving any resource belonging to the resource tree. If configured on the resource definition, the `Cache-Control` value is also shown in the describe, per resource.
`Upsert-Mode`	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 `return=minimal` to receive only those fields that are marked `includeInCompactView : true` in the response payload. See How to Control the ADF REST Response Payload Fields.
`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 expand and field parameters. Note that query string parameters can only be used on resource media types. They cannot, for example, be used when describing the resource.

Note:

The results of the GET method or the query syntax may vary depending on the ADF REST framework version used for a client request. The following 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

GET URI Parameter	Value	Description
`q` Starting in ADF REST framework version 2, `q` supports complex rowmatch expressions.	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: `<exp1>;<exp2>` Example: `?q=Deptno>=10 and <= 30;Loc!=NY` 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 `and` and `or` conjunctions with matching sets of parentheses for grouping. For example, the following expression uses conjunction to query the resource using three different fields: `(AssignedToId is null) or ( (Priority <= 2) and (RecordName like 'TT-99%'))` 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: Version 1 syntax encloses the literal value in double quotes (`"`) and requires a backslash (`\`) to escape double quote characters contained in the value: `?q=NickName="\"Billy the Kid\""` Version 2, or later, syntax encloses the literal value in single quotes (`'`) and requires a single quote to escape a single quote character contained in the value (used as an apostrophe): `?q=ListName='Bill''s list'` Additionally, in version 1, if the query parameter value contains a reserved word (such as `AND` or `OR`), then the value needs to be enclosed in single quotes (`'`) and there must be a space before and after the quoted string. For example, the string matching filter `’Accounting and Finance’` in the following query parameter expression contains the reserved word `AND`, and therefore requires a space before and after the single quotation marks to be viable in version 1 syntax: `?q=DepartmentName= 'Accounting and Finance' &fields=DepartmentName` 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 (`'`), and then enclosed again in double quotes (`"`) , along with escaping the double quotes contained within the value with a backslash (`\`), and there needs to be a space before and after the twice-quoted string. For example: `?q=DepartmentName= "'\"Accounting\" and Finance'" &fields=DepartmentName` 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: `=` (Equal to) `>` (Greater than) `<` (Less than) `>=` (Greater than or equal to) `<=` (Less than or equal to) `!=` (Not equal to) framework version 1 only `AND` (And) `OR` (Or) `NOT` (Not) `LIKE` (Like) Supported operators in framework version 2 and later also include: `<>` (Not equal to) `BETWEEN` (Between) `NOT BETWEEN` (Not between) `IN` (In) `NOT IN` (Not in) `IS NULL` (Null) `IS NOT NULL` (Not Null) Allowed special characters in framework version 1: `"` (double quotation mark) to define a literal value for use where special characters appear in the value `'` (single quotation mark) to define a literal value for use where reserved words appear in the value `\` (backslash) to define an escape character to escape a double quotation mark (`"`) or single quotation mark/apostrophe (`'`) character used within a literal value `*` (asterisk) to define a wildcard character Allowed special characters in framework version 2 and later: `'` (single quotation mark) to define a literal value or to define an escape character to escape a single quotation mark/apostrophe (`'`) character used within a literal value `%` (percent) to define a wildcard character 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.
`finder`	An expression containing the primary key attribute value definition. Format: `PrimaryKey;<PKattr1>=<PKval1>,<PKattr2>=<PKval2>,...` Example: `?finder=PrimaryKey;EmployeeId=101` Or: An expression containing information about the row finder and its finder attributes. Format: `<rowfinderName>;<attr1>=<val1>,<attr2>=<value2>` Example: `?finder=DeptByName;Dname=ACCOUNTING` 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: `?finder=EmpByName;EmpName="Jones,Bill"` If the finder attribute value is a literal value (enclosed in double quotes) and the value contains double quotation marks `"`, the contained quotation marks must be preceded by the backslash escape `\` character to be viable as a finder attribute value. For example: `?finder=EmpByName;NickName="\"Billy the Kid\""`	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 `char`, `date`, or `number`, will be filtered out. 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: `"` (double quotation mark) to define a literal value `\` (backslash) to define an escape character to escape a double quotation mark (`"`) character used within a literal value 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.
`totalResults`	boolean Default: `false`	The resource collection representation will include the estimated row count when `totalResults=true`. For an example, see Returning the Estimated Count of Resource Items.
`limit`	integer Default: Iterator binding `RangeSize` property in the ADF REST resource definition file.	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.
`offset`	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.

q

Starting in ADF REST framework version 2, q supports complex rowmatch expressions.

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: <exp1>;<exp2>

Example: ?q=Deptno>=10 and <= 30;Loc!=NY

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 and and or conjunctions with matching sets of parentheses for grouping.

For example, the following expression uses conjunction to query the resource using three different fields:

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

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:

Version 1 syntax encloses the literal value in double quotes (") and requires a backslash (\) to escape double quote characters contained in the value: ?q=NickName="\"Billy the Kid\""
Version 2, or later, syntax encloses the literal value in single quotes (') and requires a single quote to escape a single quote character contained in the value (used as an apostrophe): ?q=ListName='Bill''s list'

Additionally, in version 1, if the query parameter value contains a reserved word (such as AND or OR), then the value needs to be enclosed in single quotes (') and there must be a space before and after the quoted string. For example, the string matching filter ’Accounting and Finance’ in the following query parameter expression contains the reserved word AND, and therefore requires a space before and after the single quotation marks to be viable in version 1 syntax:

?q=DepartmentName= 'Accounting and Finance' &fields=DepartmentName

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 ('), and then enclosed again in double quotes (") , along with escaping the double quotes contained within the value with a backslash (\), and there needs to be a space before and after the twice-quoted string. For example:

?q=DepartmentName= "'\"Accounting\" and Finance'" &fields=DepartmentName

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:

= (Equal to)
> (Greater than)
< (Less than)
>= (Greater than or equal to)
<= (Less than or equal to)
!= (Not equal to) framework version 1 only
AND (And)
OR (Or)
NOT (Not)
LIKE (Like)

Supported operators in framework version 2 and later also include:

<> (Not equal to)
BETWEEN (Between)
NOT BETWEEN (Not between)
IN (In)
NOT IN (Not in)
IS NULL (Null)
IS NOT NULL (Not Null)

Allowed special characters in framework version 1:

" (double quotation mark) to define a literal value for use where special characters appear in the value
' (single quotation mark) to define a literal value for use where reserved words appear in the value
\ (backslash) to define an escape character to escape a double quotation mark (") or single quotation mark/apostrophe (') character used within a literal value
* (asterisk) to define a wildcard character

Allowed special characters in framework version 2 and later:

' (single quotation mark) to define a literal value or to define an escape character to escape a single quotation mark/apostrophe (') character used within a literal value
% (percent) to define a wildcard character

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.

finder

An expression containing the primary key attribute value definition.

Format: PrimaryKey;<PKattr1>=<PKval1>,<PKattr2>=<PKval2>,...

Example: ?finder=PrimaryKey;EmployeeId=101

Or:

An expression containing information about the row finder and its finder attributes.

Format: <rowfinderName>;<attr1>=<val1>,<attr2>=<value2>

Example: ?finder=DeptByName;Dname=ACCOUNTING

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:

?finder=EmpByName;EmpName="Jones,Bill"

If the finder attribute value is a literal value (enclosed in double quotes) and the value contains double quotation marks ", the contained quotation marks must be preceded by the backslash escape \ character to be viable as a finder attribute value. For example:

?finder=EmpByName;NickName="\"Billy the Kid\""

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 char, date, or number, will be filtered out.

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:

" (double quotation mark) to define a literal value
\ (backslash) to define an escape character to escape a double quotation mark (") character used within a literal value

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.

totalResults

boolean

Default: false

The resource collection representation will include the estimated row count when totalResults=true.

For an example, see Returning the Estimated Count of Resource Items.

limit

integer

Default: Iterator binding RangeSize property in the ADF REST resource definition file.

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.

offset

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

GET URI Parameter	Value	Description
`fields` Starting in ADF REST framework version 3 and later, `fields` will return children resource items as a resource collection to support pagination of the collection. For more information, see What Happens at Runtime: Invoking an ADF REST Framework Version.	A simple comma separate list of resource item attributes. Format: `<attr1>,<attr2>` Example: `?fields=Dname,DLoc` May be used on child resources. Format: <`accessor>:<att1>,<att2>` Example: `?fields=Employees:FirstName,LastName` May be used on nested resources using accessor dot notation. Format: <`accessor1>.<accessor2>:<Attr1>,<Attr2>` Example: `?fields=Employees.JobHistory:JobId` Or on both resources in the nested resource. Format: <`accessor1>:<Attr1>,<Attr2>;<accessor1>.<accessor2>:<Attr1>,<Attr2>` Example: `?fields=Name,Location;Employees:FirstName,LastName`	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 (`Employees.JobHistory`), then attributes may be specified on both resources. A resource in the accessor dot notation without a specified attribute will return no resource item attributes. Note this parameter cannot be combined with the `expand` parameter. If both parameters are provided, only `fields` will be considered. 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).
`onlyData`	boolean Default: `false`	The representation will be filtered in order to contain only data (no `links` objects, for example). For an example, see Returning Only Resource Data in a Payload.
`expand` Starting in ADF REST framework version 3 and later, `expand` will return children resource items as a resource collection to support pagination of the collection. For more information, see What Happens at Runtime: Invoking an ADF REST Framework Version.	Display all children. Format: `all` Display one or more child resource using a comma-separated list of accessors. Format: <`accessor1>,<accessor2>` Example: `?expand=Employees,Localizations` Display nested resources using the accessor dot notation. Format: <`accessor1>.<accessor2>` Example: `?expand=Employees.JobHistory`	When this parameter is provided, the specified children are included in the resource payload (instead of the link). Note the `expand` parameter cannot be combined with the `fields` parameter. If both parameters are provided, only `fields` will be considered. Note that if a nested resource is queried using the accessor dot notation (`Employees.JobHistory`), then the missing children will be processed implicitly. For example, `?expand=Employees.JobHistory` is the same as `?expand=Employees,Employees.JobHistory` (which will expand `Employees` and `JobHistory`). 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.
`dependency`	A set of dependency attributes. Format: `<attr1>=<val1>,<attr2>=<value2>` Example: `dependency=ProductId=2`	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 `dependency` parameter is set, the attributes will be set in the parent resource item before generating the resource collection payload.
`orderBy`	A comma separated list of order-by attributes with a sort flag to specify ascending or descending order. Format: `<orderBy_attr1_name>[:<(asc/desc)>]`, `<orderBy_attr2_name>[:<(asc/desc)>]` Example: `?orderBy=DName:desc,DLoc` 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 `upper` or `lower` flag: `upper(<orderBy_attr1_name>):<(asc)>` or `lower(<orderBy_attr2_name>)`	Sorts a resource collection based on its attributes. If the `asc`/`desc` are not provided (or an invalid value is provided), `asc` will be used as default. By default, the fetched collection will be sorted in a case sensitive way unless either the `upper` or `lower` flag is specified in the order-by query request. For an example, see Sorting a Resource Collection.
`links`	A comma separated list of `<rel_name>`, where `<rel_name>` is a string representing the relation type of a link. Example: `self,canonical`	When a resource item or a resource collection is requested and the `links` query parameter is used, then only those links with relation types ("`rel`") matching the values in the comma-separated parameter value will be shown in the response. Note the `links` parameter cannot be combined with `onlyData` when `onlyData` has a value of `true`, as there will be no links section displayed in the payload.

fields

Starting in ADF REST framework version 3 and later, fields will return children resource items as a resource collection to support pagination of the collection.

For more information, see What Happens at Runtime: Invoking an ADF REST Framework Version.

A simple comma separate list of resource item attributes.

Format: <attr1>,<attr2>

Example: ?fields=Dname,DLoc

May be used on child resources.

Format: <accessor>:<att1>,<att2>

Example: ?fields=Employees:FirstName,LastName

May be used on nested resources using accessor dot notation.

Format: <accessor1>.<accessor2>:<Attr1>,<Attr2>

Example: ?fields=Employees.JobHistory:JobId

Or on both resources in the nested resource.

Format: <accessor1>:<Attr1>,<Attr2>;<accessor1>.<accessor2>:<Attr1>,<Attr2>

Example: ?fields=Name,Location;Employees:FirstName,LastName

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 (Employees.JobHistory), then attributes may be specified on both resources. A resource in the accessor dot notation without a specified attribute will return no resource item attributes.

Note this parameter cannot be combined with the expand parameter. If both parameters are provided, only fields will be considered.

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).

onlyData

boolean

Default: false

The representation will be filtered in order to contain only data (no links objects, for example).

For an example, see Returning Only Resource Data in a Payload.

expand

Starting in ADF REST framework version 3 and later, expand will return children resource items as a resource collection to support pagination of the collection.

For more information, see What Happens at Runtime: Invoking an ADF REST Framework Version.

Display all children. Format: all

Display one or more child resource using a comma-separated list of accessors.

Format: <accessor1>,<accessor2>

Example: ?expand=Employees,Localizations

Display nested resources using the accessor dot notation.

Format: <accessor1>.<accessor2>

Example: ?expand=Employees.JobHistory

When this parameter is provided, the specified children are included in the resource payload (instead of the link).

Note the expand parameter cannot be combined with the fields parameter. If both parameters are provided, only fields will be considered.

Note that if a nested resource is queried using the accessor dot notation (Employees.JobHistory), then the missing children will be processed implicitly. For example, ?expand=Employees.JobHistory is the same as ?expand=Employees,Employees.JobHistory (which will expand Employees and JobHistory).

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.

dependency

A set of dependency attributes.

Format: <attr1>=<val1>,<attr2>=<value2>

Example: dependency=ProductId=2

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 dependency parameter is set, the attributes will be set in the parent resource item before generating the resource collection payload.

orderBy

A comma separated list of order-by attributes with a sort flag to specify ascending or descending order.

Format: <orderBy_attr1_name>[:<(asc/desc)>], <orderBy_attr2_name>[:<(asc/desc)>]

Example: ?orderBy=DName:desc,DLoc

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 upper or lower flag:

upper(<orderBy_attr1_name>):<(asc)>

or

lower(<orderBy_attr2_name>)

Sorts a resource collection based on its attributes. If the asc/desc are not provided (or an invalid value is provided), asc will be used as default.

By default, the fetched collection will be sorted in a case sensitive way unless either the upper or lower flag is specified in the order-by query request.

For an example, see Sorting a Resource Collection.

links

A comma separated list of <rel_name>, where <rel_name> is a string representing the relation type of a link.

Example: self,canonical

When a resource item or a resource collection is requested and the links query parameter is used, then only those links with relation types ("rel") matching the values in the comma-separated parameter value will be shown in the response.

Note the links parameter cannot be combined with onlyData when onlyData has a value of true, as there will be no links section displayed in the payload.

Table 22-12 Supported GET Method Query String Parameters Used in Resource Catalog Describe

GET URI Parameter	Value	Description
`metadataMode`	`verbose` (default) `minimal` `list`	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 `?metadataMode=minimal` to the describe request. If you do not want any metadata in the response but only self links, you can append `?metadataMode=list` to the describe request. 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 `showAnnotations` and `includeChildren`. For example, you can append `?metadataMode=minimal&includeChildren=true` to retrieve a minimal catalog describe with all children resources included. For an example, see Retrieving a Minimal Catalog Describe.
`showAnnotations`	`true`, `false` (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: By default, a full catalog (`metadataMode=verbose`) describe includes annotations. To exclude resource annotations from the full catalog describe, you can append `?showAnnotations=false` on the describe request. By default, a minimal catalog (`metadataMode=minimal`) describe excludes annotations. To include resource annotations in the minimal catalog describe, you can append `?showAnnotations=true` on the describe request. 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 `?metadataMode=list`.
`include`	`public` (default), `unlisted`, `all`	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 (`public`), only private resources (`unlisted`), or both types (`all`). By default, only resources that are public are shown in the describe. To view private resources, you must append either `?include=all` or ?`include=unlisted` on the describe request. 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.
`resources`	A comma separated list of resource collection names. Format:`<resName1>,<resName2>` Example: `?resources=Departments,Employees`	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

GET URI Parameter	Value	Description
`includeChildren`	`true`, `false` (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: By default, a full catalog (`metadataMode=verbose`) describe includes all children resources. To exclude children resources from the full catalog describe, you can append `?includeChildren=false` on the describe request. By default, a minimal catalog (`metadataMode=minimal`) describe excludes all children resources. To include children resources in the minimal catalog describe, you can append `?includeChildren=true` on the describe request. You cannot use this parameter with `?metadataMode=list`. For a resource catalog describe example, see Retrieving a Minimal Catalog Describe. When a resource item describe is requested and `?includeChildren=true` is provided, all children will be recursively included in the describe. For an example, see Describing a Resource Item.

includeChildren

true, false

(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:

By default, a full catalog (metadataMode=verbose) describe includes all children resources. To exclude children resources from the full catalog describe, you can append ?includeChildren=false on the describe request.
By default, a minimal catalog (metadataMode=minimal) describe excludes all children resources. To include children resources in the minimal catalog describe, you can append ?includeChildren=true on the describe request.

You cannot use this parameter with ?metadataMode=list.

For a resource catalog describe example, see Retrieving a Minimal Catalog Describe.

When a resource item describe is requested and ?includeChildren=true is provided, all children will be recursively included in the describe. For an example, see Describing a Resource Item.

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	`=` (Equal to) `.../Departments?q=Deptno = 20` `<>` (Not equal to) `.../Departments?q=Deptno <> 20` `<` (Less than) `.../Departments?q=Deptno < 20` `<=` (Less than or equal to) `.../Departments?q=Deptno <= 20` `>` (Greater than) `.../Departments?q=Deptno > 30` `>=` (Greater than or equal to) `.../Departments?q=Deptno >= 30` `BETWEEN` (Between) `.../Departments?q=Deptno BETWEEN 10 AND 30` `NOT BETWEEN` (Not between) `.../Departments?q=Deptno NOT BETWEEN 10 and 30` `IN` (In) `.../Departments?q=Deptno IN (10, 30)` `NOT IN` (Not in) `.../Departments?q=Deptno NOT IN (10, 30)` `IS NULL` (Is null) `.../Departments?q=Deptno IS NULL` `NOT NULL` (Not null) `.../Departments?q=Deptno NOT NULL`
number	`=` (Equal to) `.../Departments?q=Salary = 3120.99` `<>` (Not equal to) `.../Departments?q=Salary <> 3120.99` `<` (Less than) `.../Departments?q=Salary < 3120.99` `<=` (Less than or equal to) `.../Departments?q=Salary <= 3120.99` `>` (Greater than) `.../Departments?q=Salary > 3120.99` `>=` (Greater than or equal to) `.../Departments?q=Salary >= 3120.99` `BETWEEN` (Between) `.../Departments?q=Salary BETWEEN 2000 AND 3120.99` `NOT BETWEEN` (Not between) `.../Departments?q=Salary NOT BETWEEN 2000 and 3120.99` `IN` (In) `.../Departments?q=Salary IN (800, 3120.99)` `NOT IN` (Not in) `.../Departments?q=Salary NOT IN (800, 3120.99)` `IS NULL` (Is null) `.../Departments?q=Salary IS NULL` `NOT NULL` (Not null) `.../Departments?q=Salary NOT NULL`
string	`=` (Equal to) `.../Departments?q=DeptName = ’SALES’` `<>` (Not equal to) `.../Departments?q=DeptName <> ’SALES’` `LIKE` (Like) `.../Departments?q=DeptName LIKE ’SA%’` `.../Departments?q=DeptName LIKE ’%ES’` `.../Departments?q=UPPER(DeptName) LIKE UPPER('%e%')` `NOT LIKE` (Not like) `.../Departments?q=UPPER(DeptName) NOT LIKE UPPER('%c%')` `IN` (In) `.../Departments?q=DeptName IN ('SALES', 'RESEARCH')` `NOT IN` (Not in) `.../Departments?q=DeptName NOT IN ('SALES', 'RESEARCH')` `IS NULL` (Is null) `.../Departments?q=DeptName IS NULL` `IS NOT NULL` (Is not null) `.../Departments?q=DeptName IS NOT NULL`
date	`=` (Equal to) `.../Employees?q=HireDate = ’1999-01-01’` `<>` (Not equal to) `.../Employees?q=HireDate <> ’1999-01-01’` `<` (Less than) `.../Employees?q=HireDate < ’1999-01-01’` `<=` (Less than or equal to) `.../Employees?q=HireDate <= ’1999-01-01’` `>` (Greater than) `.../Employees?q=HireDate > ’1999-01-01’` `>=` (Greater than or equal to) `.../Employees?q=HireDate >= ’1999-01-01’` `BETWEEN` (Between) `.../Employees?q=HireDate BETWEEN ’1999-01-01’ AND ’2010-01-01’` `NOT BETWEEN` (Not between) `.../Employees?q=HireDate NOT BETWEEN ’1999-01-01’ AND ’2010-01-01’` `IS NULL` (Is null) `.../Employees?q=HireDate IS NULL` `NOT NULL` (Not null) `.../Employees?q=HireDate NOT NULL`
time	`=` (Equal to) `.../Employees?q=HireTime = '08:30:40'` `<>` (Not equal to) `.../Employees?q=HireTime <> ’08:30:40’` `<` (Less than) `.../Employees?q=HireTime < ’08:30:40’` `<=` (Less than or equal to) `.../Employees?q=HireTime <= ’08:30:40’` `>` (Greater than) `.../Employees?q=HireTime > ’08:30:40’` `>=` (Greater than or equal to) `.../Employees?q=HireTime >= ’08:30:40’` `BETWEEN` (Between) `.../Employees?q=HireTime BETWEEN ’04:30:00’ AND '08:30:40'` `NOT BETWEEN` (Not between) `.../Employees?q=HireTime NOT BETWEEN ’04:30:00’ AND '08:30:40'` `IS NULL` (Is null) `.../Employees?q=HireTime IS NULL` `NOT NULL` (Not null) `.../Employees?q=HireTime NOT NULL`
datetime Note: Both UTC and local datetime formats are supported. The value returned is determined by the time zone configured for the VM.	`=` (Equal to) `.../Employees?q=HireDateTime = '1999-01-01T08:30:40Z'` `<>` (Not equal to) `.../Employees?q=HireDateTime <> ’1999-01-01T08:30:40Z’` `<` (Less than) `.../Employees?q=HireDateTime < ’1999-01-01T08:30:40Z’` `<=` (Less than or equal to) `.../Employees?q=HireDateTime <= ’1999-01-01T08:30:40Z’` `>` (Greater than) `.../Employees?q=HireDateTime > ’1999-01-01T08:30:40Z’` `>=` (Greater than or equal to) `.../Employees?q=HireDateTime >= ’1999-01-01T08:30:40Z’` `BETWEEN` (Between) `.../Employees?q=HireDateTime BETWEEN ’1999-01-01T08:30:40Z’ AND ’1999-12-01T08:30:40Z’` `NOT BETWEEN` (Not between) `.../Employees?q=HireDateTime NOT BETWEEN ’1999-01-01T08:30:40Z’ AND ’1999-12-01T08:30:40Z’` `IS NULL` (Is null) `.../Employees?q=HireDateTime IS NULL` `NOT NULL` (Not null) `.../Employees?q=HireDateTime NOT NULL`
boolean	`= ’true’` (true) `.../Employees?q=Active = ’true’` `= ’false’` (false) `.../Employees?q=Active = ’false’` `IS NULL` (Is null) `.../Employees?q=Active IS NULL` `NOT NULL` (Not null) `.../Employees?q=Active NOT NULL`

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

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

DELETE Method

The ADF REST framework supports the following operation using a DELETE method with the URI as shown.

Deleting a resource item.

http://server/demo/rest/{version}/{resourceItemPath}

Request Parameters

none

Media Types Supported

Request
- none
Response
- none

Use Case Samples

Deleting a Resource Item