22 Consuming RESTful Web Services Using the ADF REST Framework

This chapter describes the supported HTTP methods, HTTP headers, request URL parameters, media types, and other concepts of the ADF REST runtime and the use cases that it supports for making REST API calls on resources exposed by RESTful web services. The information described in this chapter is useful to the ADF Business Components developer who wants to create RESTful web services for consumption by web service clients through a REST API.

This chapter includes the following sections:

22.1 About the ADF REST Framework

ADF provides a REST framework that supports creating and interacting with resources and 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 available (both standard CRUD operations and custom methods defined by either a view object interface or view row interface), and the view link relationships to preserve for the resulting resource.

The design-time choices made by ADF Business Components developers are captured in REST resource definition XML files. Web service client developers may interact with these resource definitions through the REST API supported by the ADF REST runtime framework. As a result, the consuming service client may invoke CRUD operations to interact with the REST resources and ADF business objects. The data is shaped by the resource's backing view object instance, with the parent-child relationships intact.

22.1.1 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 ADF REST runtime framework that will be used to process requests. The version header allows service clients to override the default version declaration defined by the REST application. In JDeveloper release 12.2.1.2.0, versions 1, 2, 3 exist.

  • Interacting with the REST resource using standard HTTP request methods, including GET, POST, PATCH, and DELETE.

  • Executing an HTTP method using an X-HTTP-Method-Override header using a POST request method when client restrictions prevent the use of standard HTTP methods to interact with the REST resource.

  • Locating a REST resource item (such as a specific employee) or resource collection (such as an collection of all employees) is supported by REST-compliant URI path names based on resource names defined in the ADF Business Components Model project.

  • Obtaining a description of the REST resource, including the resource collection attributes and available actions, is supported by a specific media type and describe action.

  • Linking to a canonical REST resource is supported when a resource with a super set of updatable entities is defined. The canonical link supports alternate links for the backing view object.

  • Filtering of the REST resource is supported by query string parameters on the URI specified by the client to access the specific resource.

  • Encoding formats are supported on the REST resource to enable compression and decompression.

  • Content streaming of BLOB and CLOB attributes exposed by the REST resource is supported by the ADF REST framework.

  • Performing data consistency checks while invoking the RESTful web service is supported by the ADF REST framework. This capability uses version history in the database to enable clients to manage HTTP payloads according to updates in the resource itself.

  • Passing a custom header to specify the ADF REST framework version (for example, version 2) with which the ADF REST runtime will use to process the request. The ADF REST framework version permits service clients to opt into framework enhancements made by Oracle in subsequent releases of Oracle JDeveloper.

  • Authorizing users to access the REST resource is enabled by ADF Security permission grants.

Specific design time features of ADF REST framework that affect the availability of runtime functionality include:

  • Registering REST resources with an application-specific resource version name (or number) to support versioning of REST resources. REST resource versions are named in the adf-config.xml file for the application.

  • Declaring a default ADF REST framework version for individual REST resources to ensure the ADF REST runtime executes requests using functionality offered by a particular ADF REST framework version. Declaring a particular framework version allows service clients to opt into framework enhancements made by Oracle in subsequent releases of Oracle JDeveloper. The default ADF REST framework version is declared in the adf-config.xml file for the application. In JDeveloper release 12.2.1.2.0, versions 1, 2, 3 exist.

  • Defining List of Value (LOV) attributes on the view object backing the resource to expose LOV accessor links in the URL resource path.

  • Defining row finders to locate a resource using the row finder key value in the URL resource path.

  • Defining client methods on the view client interface or view row client interface to expose custom actions that may be invoked using a request payload on an HTTP method.

  • Defining view instance of the application data model using a super set of updatable attributes to expose canonical links in the URL resource path.

  • Configuring change-indicator attributes on the entity object backing the resource to enable data consistency checking when making requests to access resources on the server.

  • Configuring a custom content type on the BLOB or CLOB attribute of the view object backing the resource to support content streaming using a link exposed in the resource.

  • Configuring security to authenticate users before allowing access to the resource.

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

22.1.3 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

This image is described in the surrounding text

22.1.3.1 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

This image is described in the surrounding text

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

This image is described in the surrounding text

22.1.3.2 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

This image is described in the surrounding text

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

This image is described in the surrounding text

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

This image is described in the surrounding text

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

This image is described in the surrounding text

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

This image is described in the surrounding text

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

This image is described in the surrounding text

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

This image is described in the surrounding text

22.1.3.3 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

This image is described in the surrounding text

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

This image is described in the surrounding text

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

This image is described in the surrounding text

As Figure 22-14 shows, the EmployeesView view object defines a custom service method multiplySalary for use with the Employees resource. Because the method is defined on the view row interface, it will be exposed as a custom action at the level of resource items (specific employees), not resource collections (all employees). Only methods defined on the view object client interface will operate on resource collections.

Figure 22-14 REST Sample Project - Employees View Row Interface Custom Method

This image is described in the surrounding text

As Figure 22-15 shows, the Departments entity object defines the change-indicator attribute RelState to enable support for data consistency checking. The editor for the attributes has the Change Indicator and History Column - version number fields enabled to configure the change indicator.

Figure 22-15 REST Sample Project - Departments Change Indicator Attribute

This image is described in the surrounding text

22.2 Understanding ADF Business Components Resources

With RESTful web service, the ADF Business Components view objects are represented as resource collection when 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.

22.3 Retrieving the ADF REST Resource Describe

When you invoke a 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 all available resources (resource catalog).

  • Describe a single resource collection.

  • Describe a single resource item.

  • Describe a nested resource in a parent-child relationship.

To retrieve the describe, invoke an HTTP GET with /describe appended to the resource URL.

Note:

Executing a GET request to retrieve a resource describe also requires the client to be in the context of a particular version. For information on how to get the version release names for the service end point, see Retrieving Resource Versions.

For example, the following URL returns the describe for the Employees resource of version 11.0 in the identified application:

http://host:port/context-root/rest/11.0/Employees/describe

To retrieve the describe of all the resources of a specific version in the application, you append /describe to the version URL.

For example, the following URL returns the describe for all resources of version 11.0 in the identified application:

http://host:port/context-root/rest/11.0/describe

22.3.1 Describing All Available Resources

ADF REST runtime supports describing all available resources for the application end point using a GET method.

To examine all available resources in the resource catalog:

  1. Execute the resource catalog describe and locate the names of the resources in the describe. The children attribute identifies nested resources.

  2. Examine these resource objects to understand the shape of each resource:

    • attributes specifies the list of available resource collection attributes.

    • collection specifies the shape of the collection and specifies finder for row finder, links, and available actions (including media types).

    • item specifies the shape of the instances of the collection and itself specifies links and available actions.

    • children specifies any nested resources (and itself contains attributes, collection, and item objects).

Note:

You can use the include query parameter for the catalog describe to include the description of resources of a certain visibility. For example, you can use http://server/demo/rest/v1/describe?include=all. You can use all, unlisted, or public as value for the include query parameter. You can use the values as comma-separated list like ?include=all, unlisted.

For more information on visibility, see How to Hide a Resource.

For example, the describe for a service with Departments and child Employees resources returns the following objects:

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

The following sample describes version 11.0 of all resources in the resource catalog. Note that the URL version parameter 11.0 may be replaced with an application-specific version identifier. For more details about specifying resource versions, see in Retrieving Resource Versions.

Request

  • URL

    http://server/demo/rest/11.0/describe

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

    none

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.description+json

  • Payload

    {
      "Resources" : {
        "Employees" : {
          "discrColumnType" : false,
          "attributes" : [ {
            "name" : "EmployeeId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 6
          }, {
            "name" : "FirstName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 20
          }, {
            "name" : "LastName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "Email",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "JobId",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 10,
            "controlType" : "choice",
            "maxLength" : "10",
            "lov" : {
              "childRef" : "JobsLOV",
              "attributeMap" : [ {
                "source" : "JobTitle",
                "target" : "JobId"
              } ],
              "displayAttributes" : [ "JobTitle" ]
            }
          }, {
            "name" : "DepartmentId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 4
          }, {
            "name" : "Salary",
            "type" : "number",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 8,
            "scale" : 2
          }, {
            "name" : "Picture",
            "type" : "attachment",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : false,
            "actions" : [ {
              "name" : "replace",
              "method" : "PUT",
              "requestType" : [ "image/png" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            }, {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "image/png" ]
            } ]
          } ],
          "collection" : {
            "rangeSize" : 24,
            "finders" : [ {
              "name" : "EmpByEmailFinder",
              "title" : "EmployeesByEmailVC",
              "attributes" : [ {
                "name" : "Email",
                "type" : "string",
                "updatable" : true,
                "required" : "Optional",
                "queryable" : false
              } ]
            }, {
              "name" : "PrimaryKey",
              "attributes" : [ {
                "name" : "EmployeeId",
                "type" : "integer",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 6
              } ]
            } ],
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Employees",
              "name" : "self",
              "kind" : "collection"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
            }, {
              "name" : "create",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            } ]
          },
          "item" : {
            "links" : [ {
              "rel" : "lov",
              "href" : "http://server/demo/rest/11.0/Employees/{id}/lov/JobsLOV",
              "name" : "JobsLOV",
              "kind" : "collection"
            }, {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Employees/{id}",
              "name" : "self",
              "kind" : "item"
            }, {
              "rel" : "canonical",
              "href" : "http://server/demo/rest/11.0/Employees/{id}",
              "name" : "canonical",
              "kind" : "item"
            }, {
              "rel" : "enclosure",
              "href" : "http://server/demo/rest/11.0/Employees/enclosure/Picture",
              "name" : "Picture",
              "kind" : "other"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            }, {
              "name" : "multiplySalary",
              "parameters" : [ {
                "name" : "multiplicand",
                "type" : "number",
                "mandatory" : false
              } ],
              "resultType" : "number",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.action+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
            } ]
          },
          "children" : {
            "JobsLOV" : {
              "discrColumnType" : false,
              "attributes" : [ {
                "name" : "JobId",
                "type" : "string",
                "updatable" : false,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 10
              }, {
                "name" : "JobTitle",
                "type" : "string",
                "updatable" : false,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 35
              }, {
                "name" : "MinSalary",
                "type" : "integer",
                "updatable" : false,
                "mandatory" : false,
                "queryable" : true,
                "precision" : 6
              }, {
                "name" : "MaxSalary",
                "type" : "integer",
                "updatable" : false,
                "mandatory" : false,
                "queryable" : true,
                "precision" : 6
              } ],
              "collection" : {
                "rangeSize" : 0,
                "finders" : [ {
                  "name" : "PrimaryKey",
                  "attributes" : [ {
                    "name" : "JobId",
                    "type" : "string",
                    "updatable" : false,
                    "mandatory" : true,
                    "queryable" : true,
                    "precision" : 10
                  } ]
                } ],
                "links" : [ {
                  "rel" : "self",
                  "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV",
                  "name" : "self",
                  "kind" : "collection"
                } ],
                "actions" : [ {
                  "name" : "get",
                  "method" : "GET",
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
                }, {
                  "name" : "create",
                  "method" : "POST",
                  "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                } ]
              },
              "item" : {
                "links" : [ {
                  "rel" : "self",
                  "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/{id}",
                  "name" : "self",
                  "kind" : "item"
                }, {
                  "rel" : "parent",
                  "href" : "http://server/demo/rest/11.0/Employees/{id}",
                  "name" : "parent",
                  "kind" : "item"
                }, {
                  "rel" : "canonical",
                  "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/{id}",
                  "name" : "canonical",
                  "kind" : "item"
                } ],
                "actions" : [ {
                  "name" : "get",
                  "method" : "GET",
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                }, {
                  "name" : "update",
                  "method" : "PATCH",
                  "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                }, {
                  "name" : "replace",
                  "method" : "PUT",
                  "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                }, {
                  "name" : "delete",
                  "method" : "DELETE"
                } ]
              },
              "links" : [ {
                "rel" : "self",
                "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/describe",
                "name" : "self",
                "kind" : "describe"
              }, {
                "rel" : "canonical",
                "href" : "http://server/demo/rest/11.0/Employees/{id}/child/JobsLOV/describe",
                "name" : "canonical",
                "kind" : "describe"
              } ]
            }
          },
          "links" : [ {
            "rel" : "self",
            "href" : "http://server/demo/rest/11.0/Employees/describe",
            "name" : "self",
            "kind" : "describe"
          }, {
            "rel" : "canonical",
            "href" : "http://server/demo/rest/11.0/Employees/describe",
            "name" : "canonical",
            "kind" : "describe"
          } ]
        },
        "Departments" : {
          "discrColumnType" : false,
          "attributes" : [ {
            "name" : "DepartmentId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 4
          }, {
            "name" : "DepartmentName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 30
          }, {
            "name" : "RelState",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true
          } ],
          "collection" : {
            "rangeSize" : 24,
            "finders" : [ {
              "name" : "PrimaryKey",
              "attributes" : [ {
                "name" : "DepartmentId",
                "type" : "integer",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 4
              } ]
            } ],
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Departments",
              "name" : "self",
              "kind" : "collection"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
            }, {
              "name" : "create",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "testImpl",
              "parameters" : [ {
                "name" : "testid",
                "type" : "string",
                "mandatory" : false
              } ],
              "resultType" : "string",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.action+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
            } ]
          },
          "item" : {
            "links" : [ {
              "rel" : "child",
              "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees",
              "name" : "Employees",
              "kind" : "collection",
              "cardinality" : {
                "value" : "1 to *",
                "sourceAttributes" : "DepartmentId",
                "destinationAttributes" : "DepartmentId"
              }
            }, {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Departments/{id}",
              "name" : "self",
              "kind" : "item"
            }, {
              "rel" : "canonical",
              "href" : "http://server/demo/rest/11.0/Departments/{id}",
              "name" : "canonical",
              "kind" : "item"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "update",
              "method" : "PATCH",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "replace",
              "method" : "PUT",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            } ]
          },
          "children" : {
            "Employees" : {
              "discrColumnType" : false,
              "attributes" : [ {
                "name" : "EmployeeId",
                "type" : "integer",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 6
              }, {
                "name" : "FirstName",
                "type" : "string",
                "updatable" : true,
                "mandatory" : false,
                "queryable" : true,
                "precision" : 20
              }, {
                "name" : "LastName",
                "type" : "string",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 25
              }, {
                "name" : "Email",
                "type" : "string",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 25
              }, {
                "name" : "JobId",
                "type" : "string",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 10,
                "controlType" : "choice",
                "maxLength" : "10",
                "lov" : {
                  "childRef" : "JobsLOV",
                  "attributeMap" : [ {
                    "source" : "JobTitle",
                    "target" : "JobId"
                  } ],
                  "displayAttributes" : [ "JobTitle" ]
                }
              }, {
                "name" : "DepartmentId",
                "type" : "integer",
                "updatable" : true,
                "mandatory" : false,
                "queryable" : true,
                "precision" : 4
              }, {
                "name" : "Salary",
                "type" : "number",
                "updatable" : true,
                "mandatory" : false,
                "queryable" : true,
                "precision" : 8,
                "scale" : 2
              }, {
                "name" : "Picture",
                "type" : "attachment",
                "updatable" : true,
                "mandatory" : false,
                "queryable" : false,
                "actions" : [ {
                  "name" : "replace",
                  "method" : "PUT",
                  "requestType" : [ "image/png" ]
                }, {
                  "name" : "delete",
                  "method" : "DELETE"
                }, {
                  "name" : "get",
                  "method" : "GET",
                  "responseType" : [ "image/png" ]
                } ]
              } ],
              "collection" : {
                "rangeSize" : 0,
                "finders" : [ {
                  "name" : "EmpByEmailFinder",
                  "title" : "EmployeesByEmailVC",
                  "attributes" : [ {
                    "name" : "Email",
                    "type" : "string",
                    "updatable" : true,
                    "required" : "Optional",
                    "queryable" : false
                  } ]
                }, {
                  "name" : "PrimaryKey",
                  "attributes" : [ {
                    "name" : "EmployeeId",
                    "type" : "integer",
                    "updatable" : true,
                    "mandatory" : true,
                    "queryable" : true,
                    "precision" : 6
                  } ]
                } ],
                "links" : [ {
                  "rel" : "self",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees",
                  "name" : "self",
                  "kind" : "collection"
                } ],
                "actions" : [ {
                  "name" : "get",
                  "method" : "GET",
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
                }, {
                  "name" : "create",
                  "method" : "POST",
                  "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                } ]
              },
              "item" : {
                "links" : [ {
                  "rel" : "self",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}",
                  "name" : "self",
                  "kind" : "item"
                }, {
                  "rel" : "parent",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}",
                  "name" : "parent",
                  "kind" : "item"
                }, {
                  "rel" : "canonical",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}",
                  "name" : "canonical",
                  "kind" : "item"
                }, {
                  "rel" : "enclosure",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}/enclosure/Picture",
                  "name" : "Picture",
                  "kind" : "other"
                } ],
                "actions" : [ {
                  "name" : "get",
                  "method" : "GET",
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                }, {
                  "name" : "update",
                  "method" : "PATCH",
                  "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                }, {
                  "name" : "replace",
                  "method" : "PUT",
                  "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                }, {
                  "name" : "delete",
                  "method" : "DELETE"
                }, {
                  "name" : "multiplySalary",
                  "parameters" : [ {
                    "name" : "multiplicand",
                    "type" : "number",
                    "mandatory" : false
                  } ],
                  "resultType" : "number",
                  "method" : "POST",
                  "requestType" : [ "application/vnd.oracle.adf.action+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
                } ]
              },
              "links" : [ {
                "rel" : "self",
                "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe",
                "name" : "self",
                "kind" : "describe"
              }, {
                "rel" : "canonical",
                "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe",
                "name" : "canonical",
                "kind" : "describe"
              } ]
            }
          },
          "links" : [ {
            "rel" : "self",
            "href" : "http://server/demo/rest/11.0/Departments/describe",
            "name" : "self",
            "kind" : "describe"
          }, {
            "rel" : "canonical",
            "href" : "http://server/demo/rest/11.0/Departments/describe",
            "name" : "canonical",
            "kind" : "describe"
          } ]
        }
      }
    }
    

22.3.2 Describing a Resource Collection

The ADF REST runtime supports describing resource collections using a GET method.

To examine a resource collection:

  1. Execute the resource collection describe and locate the names of the resources in the describe.

  2. Examine these resource objects to understand the shape of each resource:

    • attributes specifies the list of available resource collection attributes.

    • collection specifies the shape of the collection and specifies finder for row finder, links, and available actions (including media types).

    • item specifies the shape of the instances of the collection and itself specifies links and available actions.

    • children specifies any nested resources (and itself contains attributes, collection, and item objects).

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

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

The following sample describes version 11.0 of the Departments resource.

Request

  • URL

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

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

    none

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.description+json

  • Payload

    {
      "Resources" : {
        "Departments" : {
          "discrColumnType" : false,
          "attributes" : [ {
            "name" : "DepartmentId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 4
          }, {
            "name" : "DepartmentName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 30
          }, {
            "name" : "RelState",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true
          } ],
          "collection" : {
            "rangeSize" : 25,
            "finders" : [ {
              "name" : "PrimaryKey",
              "attributes" : [ {
                "name" : "DepartmentId",
                "type" : "integer",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 4
              } ]
            } ],
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Departments",
              "name" : "self",
              "kind" : "collection"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
            }, {
              "name" : "create",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "testImpl",
              "parameters" : [ {
                "name" : "testid",
                "type" : "string",
                "mandatory" : false
              } ],
              "resultType" : "string",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.action+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
            } ]
          },
          "item" : {
            "links" : [ {
              "rel" : "child",
              "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees",
              "name" : "Employees",
              "kind" : "collection",
              "cardinality" : {
                "value" : "1 to *",
                "sourceAttributes" : "DepartmentId",
                "destinationAttributes" : "DepartmentId"
              }
            }, {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Departments/{id}",
              "name" : "self",
              "kind" : "item"
            }, {
              "rel" : "canonical",
              "href" : "http://server/demo/rest/11.0/Departments/{id}",
              "name" : "canonical",
              "kind" : "item"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "update",
              "method" : "PATCH",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "replace",
              "method" : "PUT",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            } ]
          },
          "children" : {
            "Employees" : {
              "discrColumnType" : false,
              "attributes" : [ {
                "name" : "EmployeeId",
                "type" : "integer",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 6
              }, {
                "name" : "FirstName",
                "type" : "string",
                "updatable" : true,
                "mandatory" : false,
                "queryable" : true,
                "precision" : 20
              }, {
                "name" : "LastName",
                "type" : "string",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 25
              }, {
                "name" : "Email",
                "type" : "string",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 25
              }, {
                "name" : "JobId",
                "type" : "string",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 10,
                "controlType" : "choice",
                "maxLength" : "10",
                "lov" : {
                  "childRef" : "JobsLOV",
                  "attributeMap" : [ {
                    "source" : "JobTitle",
                    "target" : "JobId"
                  } ],
                  "displayAttributes" : [ "JobTitle" ]
                }
              }, {
                "name" : "DepartmentId",
                "type" : "integer",
                "updatable" : true,
                "mandatory" : false,
                "queryable" : true,
                "precision" : 4
              }, {
                "name" : "Salary",
                "type" : "number",
                "updatable" : true,
                "mandatory" : false,
                "queryable" : true,
                "precision" : 8,
                "scale" : 2
              }, {
                "name" : "Picture",
                "type" : "attachment",
                "updatable" : true,
                "mandatory" : false,
                "queryable" : false,
                "actions" : [ {
                  "name" : "replace",
                  "method" : "PUT",
                  "requestType" : [ "image/png" ]
                }, {
                  "name" : "delete",
                  "method" : "DELETE"
                }, {
                  "name" : "get",
                  "method" : "GET",
                  "responseType" : [ "image/png" ]
                } ]
              } ],
              "collection" : {
                "rangeSize" : 0,
                "finders" : [ {
                  "name" : "EmpByEmailFinder",
                  "title" : "EmployeesByEmailVC",
                  "attributes" : [ {
                    "name" : "Email",
                    "type" : "string",
                    "updatable" : true,
                    "required" : "Optional",
                    "queryable" : false
                  } ]
                }, {
                  "name" : "PrimaryKey",
                  "attributes" : [ {
                    "name" : "EmployeeId",
                    "type" : "integer",
                    "updatable" : true,
                    "mandatory" : true,
                    "queryable" : true,
                    "precision" : 6
                  } ]
                } ],
                "links" : [ {
                  "rel" : "self",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees",
                  "name" : "self",
                  "kind" : "collection"
                } ],
                "actions" : [ {
                  "name" : "get",
                  "method" : "GET",
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
                }, {
                  "name" : "create",
                  "method" : "POST",
                  "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                } ]
              },
              "item" : {
                "links" : [ {
                  "rel" : "self",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}",
                  "name" : "self",
                  "kind" : "item"
                }, {
                  "rel" : "parent",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}",
                  "name" : "parent",
                  "kind" : "item"
                }, {
                  "rel" : "canonical",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}",
                  "name" : "canonical",
                  "kind" : "item"
                }, {
                  "rel" : "enclosure",
                  "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/{id}/enclosure/Picture",
                  "name" : "Picture",
                  "kind" : "other"
                } ],
                "actions" : [ {
                  "name" : "get",
                  "method" : "GET",
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                }, {
                  "name" : "update",
                  "method" : "PATCH",
                  "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                }, {
                  "name" : "replace",
                  "method" : "PUT",
                  "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
                }, {
                  "name" : "delete",
                  "method" : "DELETE"
                }, {
                  "name" : "multiplySalary",
                  "parameters" : [ {
                    "name" : "multiplicand",
                    "type" : "number",
                    "mandatory" : false
                  } ],
                  "resultType" : "number",
                  "method" : "POST",
                  "requestType" : [ "application/vnd.oracle.adf.action+json" ],
                  "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
                } ]
              },
              "links" : [ {
                "rel" : "self",
                "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe",
                "name" : "self",
                "kind" : "describe"
              }, {
                "rel" : "canonical",
                "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees/describe",
                "name" : "canonical",
                "kind" : "describe"
              } ]
            }
          },
          "links" : [ {
            "rel" : "self",
            "href" : "http://server/demo/rest/11.0/Departments/describe",
            "name" : "self",
            "kind" : "describe"
          }, {
            "rel" : "canonical",
            "href" : "http://server/demo/rest/11.0/Departments/describe",
            "name" : "canonical",
            "kind" : "describe"
          } ]
        }
      }
    }
    

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

  1. Execute the resource item describe and locate the names of the resources in the describe. The children attribute identifies nested resources.

  2. Examine the resource item describe to understand its shape.

    • attributes specifies the list of available resource collection attributes.

    • item specifies links to the item, including defined child collections, and available actions.

    • links specifies describe links.

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

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

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

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

Request

  • URL

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

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

    none

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.description+json

  • Payload

    {
      "Resources" : {
        "Departments" : {
          "discrColumnType" : false,
          "attributes" : [ {
            "name" : "DepartmentId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 4
          }, {
            "name" : "DepartmentName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 30
          }, {
            "name" : "RelState",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true
          } ],
          "item" : {
            "links" : [ {
              "rel" : "child",
              "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
              "name" : "Employees",
              "kind" : "collection",
              "cardinality" : {
                "value" : "1 to *",
                "sourceAttributes" : "DepartmentId",
                "destinationAttributes" : "DepartmentId"
              }
            }, {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Departments/10",
              "name" : "self",
              "kind" : "item"
            }, {
              "rel" : "canonical",
              "href" : "http://server/demo/rest/11.0/Departments/10",
              "name" : "canonical",
              "kind" : "item"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "update",
              "method" : "PATCH",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "replace",
              "method" : "PUT",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            } ]
          },
          "links" : [ {
            "rel" : "self",
            "href" : "http://server/demo/rest/11.0/Departments/10/describe",
            "name" : "self",
            "kind" : "describe"
          }, {
            "rel" : "canonical",
            "href" : "http://server/demo/rest/11.0/Departments/10/describe",
            "name" : "canonical",
            "kind" : "describe"
          } ]
        }
      }
    }
    

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

  1. Execute the nested resource describe and locate the names of the resources in the describe. The children attribute identifies nested resources.

  2. Examine these resource objects to understand the shape of each resource:

    • attributes specifies the list of available resource collection attributes.

    • collection specifies the shape of the collection and specifies finder for row finder, links, and available actions (including media types).

    • item specifies the shape of the instances of the collection and itself specifies links and available actions.

    • children specifies the nested resources (and itself contains attributes, collection, and item objects).

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

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

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

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

Requests

  • URL 1

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

  • URL 2

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

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

    none

Responses

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.description+json

  • Payload 1

    {
      "Resources" : {
        "Employees" : {
          "discrColumnType" : false,
          "attributes" : [ {
            "name" : "EmployeeId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 6
          }, {
            "name" : "FirstName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 20
          }, {
            "name" : "LastName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "Email",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "JobId",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 10,
            "controlType" : "choice",
            "maxLength" : "10",
            "lov" : {
              "childRef" : "JobsLOV",
              "attributeMap" : [ {
                "source" : "JobTitle",
                "target" : "JobId"
              } ],
              "displayAttributes" : [ "JobTitle" ]
            }
          }, {
            "name" : "DepartmentId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 4
          }, {
            "name" : "Salary",
            "type" : "number",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 8,
            "scale" : 2
          }, {
            "name" : "Picture",
            "type" : "attachment",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : false,
            "actions" : [ {
              "name" : "replace",
              "method" : "PUT",
              "requestType" : [ "image/png" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            }, {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "image/png" ]
            } ]
          } ],
          "collection" : {
            "rangeSize" : 25,
            "finders" : [ {
              "name" : "EmpByEmailFinder",
              "title" : "EmployeesByEmailVC",
              "attributes" : [ {
                "name" : "Email",
                "type" : "string",
                "updatable" : true,
                "required" : "Optional",
                "queryable" : false
              } ]
            }, {
              "name" : "PrimaryKey",
              "attributes" : [ {
                "name" : "EmployeeId",
                "type" : "integer",
                "updatable" : true,
                "mandatory" : true,
                "queryable" : true,
                "precision" : 6
              } ]
            } ],
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
              "name" : "self",
              "kind" : "collection"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourcecollection+json" ]
            }, {
              "name" : "create",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            } ]
          },
          "item" : {
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/{id}",
              "name" : "self",
              "kind" : "item"
            }, {
              "rel" : "parent",
              "href" : "http://server/demo/rest/11.0/Departments/10",
              "name" : "parent",
              "kind" : "item"
            }, {
              "rel" : "canonical",
              "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/{id}",
              "name" : "canonical",
              "kind" : "item"
            }, {
              "rel" : "enclosure",
              "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/enclosure/Picture",
              "name" : "Picture",
              "kind" : "other"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "update",
              "method" : "PATCH",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "replace",
              "method" : "PUT",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            }, {
              "name" : "multiplySalary",
              "parameters" : [ {
                "name" : "multiplicand",
                "type" : "number",
                "mandatory" : false
              } ],
              "resultType" : "number",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.action+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
            } ]
          },
          "links" : [ {
            "rel" : "self",
            "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/describe",
            "name" : "self",
            "kind" : "describe"
          }, {
            "rel" : "canonical",
            "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/describe",
            "name" : "canonical",
            "kind" : "describe"
          } ]
        }
      }
    }
    
  • Payload 2

    {
      "Resources" : {
        "Employees" : {
          "discrColumnType" : false,
          "attributes" : [ {
            "name" : "EmployeeId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 6
          }, {
            "name" : "FirstName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 20
          }, {
            "name" : "LastName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "Email",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "JobId",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 10,
            "controlType" : "choice",
            "maxLength" : "10",
            "lov" : {
              "childRef" : "JobsLOV",
              "attributeMap" : [ {
                "source" : "JobTitle",
                "target" : "JobId"
              } ],
              "displayAttributes" : [ "JobTitle" ]
            }
          }, {
            "name" : "DepartmentId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 4
          }, {
            "name" : "Salary",
            "type" : "number",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 8,
            "scale" : 2
          }, {
            "name" : "Picture",
            "type" : "attachment",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : false,
            "actions" : [ {
              "name" : "replace",
              "method" : "PUT",
              "requestType" : [ "image/png" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            }, {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "image/png" ]
            } ]
          } ],
          "item" : {
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200",
              "name" : "self",
              "kind" : "item"
            }, {
              "rel" : "parent",
              "href" : "http://server/demo/rest/11.0/Departments/10",
              "name" : "parent",
              "kind" : "item"
            }, {
              "rel" : "canonical",
              "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200",
              "name" : "canonical",
              "kind" : "item"
            }, {
              "rel" : "enclosure",
              "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200/enclosure/Picture",
              "name" : "Picture",
              "kind" : "other"
            } ],
            "actions" : [ {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "update",
              "method" : "PATCH",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "replace",
              "method" : "PUT",
              "requestType" : [ "application/vnd.oracle.adf.resourceitem+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.resourceitem+json" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            }, {
              "name" : "multiplySalary",
              "parameters" : [ {
                "name" : "multiplicand",
                "type" : "number",
                "mandatory" : false
              } ],
              "resultType" : "number",
              "method" : "POST",
              "requestType" : [ "application/vnd.oracle.adf.action+json" ],
              "responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
            } ]
          },
          "links" : [ {
            "rel" : "self",
            "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200/describe",
            "name" : "self",
            "kind" : "describe"
          }, {
            "rel" : "canonical",
            "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees/200/describe",
            "name" : "canonical",
            "kind" : "describe"
          } ]
        }
      }
    }
    

22.3.5 Understanding the links Object Structure in the ADF REST describe

links is a JSON object where the value is always a URL link and the link name is defined according to the rel of the link. The links object is generated for each resource collection, item, and for the resource itself.

Note that URL links in the resource describe will be generated using a template placeholder value ({id}) when there is not enough information to determine all parts of the URL. For example, the following child link provides a URL with the placeholder for the value of the specific Department resource:

"item" : {
     "links" : [ {
        "rel" : "child",
        "href" : "http://server/demo/rest/11.0/Departments/{id}/child/Employees",
        "name" : "Employees",
        "kind" : "collection",
        "cardinality" : {
          "value" : "1 to *",
          "sourceAttributes" : "DepartmentId",
          "destinationAttributes" : "DepartmentId"
        }

22.3.5.1 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-2.

Table 22-2 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 <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.

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.

22.3.5.2 href Attribute Value

The href attribute defines the URL to the linked resource or resource describe.

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

22.4 Retrieving Resource Versions

In ADF, you can create version identifiers for 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, just the latest version, or only a specific version.

Additionally, the REST resource developer can assign a lifecycle status (active, desupported, deprecated) when they create or update a version identifier. Resources that have been tagged deprecated are handled as valid resources and that status has no runtime impact. Whereas, resources that have been tagged with the lifecycle status desupported will no longer be accessible by the service client and requests for desupported versions will return the following error message:

JBO-29151: The requested version 'x' has been desupported.

If the service client requests a resource that does not exist for the requested version, the ADF REST runtime will fallback to a previous version with status active or deprecated. Thus, if the Departments resource versions 11.0 and 11.1 exist but 11.2 does not, the request for version 11.2 will return the next more recent resource, version 11.1.

22.4.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:

  1. Execute the service end point describe and locate the available release version names in the describe.

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

  3. 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_identfier",
                    "allowedFrameworkVersions" : [ "framework_identfier1", "framework_identfier2", ... ]

            },
            "links" : [
                {
                    "rel" : "self",
                    ...
 
                },
                {
                    "rel" : "canonical",
                    ...
 
                },
                {
                    "rel" : "predecessor-version",
                    ...
 
                },
                {
                    "rel" : "describe",
                    ...
 
                }
            ]
        },
        {
            "version" : "version_identifier_previous",
            "adf:extension" : {
                    "defaultFrameworkVersion" : "framework_identfier",
                    "allowedFrameworkVersions" : [ "framework_identfier1", "framework_identfier2", ... ]
            },
            "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"
            }
        ]
    }
    

22.4.2 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" : "replace",
              "method" : "PUT",
              "requestType" : [ "image/png" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            }, {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "image/png" ]
            } ]
          } ],
          "collection" : {
               ...
              } ]
            } ],
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.0/Employees",
              "name" : "self",
              "kind" : "collection"
            } ],
            "actions" : [ {
              ...
            } ]
          },
          "item" : {
            "links" : [ {
              ...
            } ],
          },
          "links" : [ {
            "rel" : "self",
            "href" : "http://server/demo/rest/11.0/Employees/describe",
            "name" : "self",
            "kind" : "describe"
          }, {
            "rel" : "canonical",
            "href" : "http://server/demo/rest/11.0/Employees/describe",
            "name" : "canonical",
            "kind" : "describe"
          } ]
        }
      }
    }
    

Request Version 2

  • URL 2

    http://server/demo/rest/11.1/Departments

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

    none

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.describe+json

  • Payload 2

    {
      "Resources" : {
        "Employees" : {
          "discrColumnType" : false,
          "title" : "Employees All Attributes",
            "name" : "EmployeeId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 6
          }, {
            "name" : "FirstName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 20
          }, {
            "name" : "LastName",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "Email",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 25
          }, {
            "name" : "JobId",
            "type" : "string",
            "updatable" : true,
            "mandatory" : true,
            "queryable" : true,
            "precision" : 10
          }, {
            "name" : "DepartmentId",
            "type" : "integer",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 4
          }, {
            "name" : "Salary",
            "type" : "number",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 8,
            "scale" : 2
          }, {
            "name" : "Picture",
            "type" : "attachment",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : false,
            "actions" : [ {
              "name" : "replace",
              "method" : "PUT",
              "requestType" : [ "image/png" ]
            }, {
              "name" : "delete",
              "method" : "DELETE"
            }, {
              "name" : "get",
              "method" : "GET",
              "responseType" : [ "image/png" ]
            } ]
          }, {
            "name" : "HireDate",
            "type" : "string",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true
          }, {
            "name" : "PhoneNumber",
            "type" : "string",
            "updatable" : true,
            "mandatory" : false,
            "queryable" : true,
            "precision" : 20
          } ],
          "collection" : {
               ...
              } ]
            } ],
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.1/Employees",
              "name" : "self",
              "kind" : "collection"
            } ],
            "actions" : [ {
              ...
            } ]
          },
          "item" : {
            "links" : [ {
              ...
            } ]
          },
          "links" : [ {
            "rel" : "self",
            "href" : "http://server/demo/rest/11.1/Employees/describe",
            "name" : "self",
            "kind" : "describe"
          }, {
            "rel" : "canonical",
            "href" : "http://server/demo/rest/11.1/Employees/describe",
            "name" : "canonical",
            "kind" : "describe"
          } ]
        }
      }
    }
    

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

22.5.1 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"
      } ]
    }
    

22.5.2 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" : 25
      "offset" : 4,
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/11.0/Departments",
        "name" : "Departments",
        "kind" : "collection"
      } ]
    }
    

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

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

  2. 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"
      } ]
    }
    

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

By default, resource and resource items names used in query parameter operations are case sensitive. If case insensitive filtering is desired, you may set the flag restV1QueryCaseSensitive in the adf-config.xml file to false. The default value of the flag is true which implies case sensitive filtering.

ADF REST Framework Version 2 (and later)

Starting with version 2 of the ADF REST framework, service clients may use an advanced query syntax, also known as rowmatch expressions, to fetch resources. For a complete description of the query syntax available in version 2 (and later), What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2.

The following sample fetches departments with names that begin with SA (for example, SALES) or have a Location of BOSTON.

Request Made With Framework Version 2

  • URL

    http://server/demo/rest/11.1/Departments?q=DepartmentName like 'SA*' or Location = 'BOSTON'

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

    none

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.

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"
      } ]
    }
    

22.5.5 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"
      } ]
    }
    

22.5.6 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
                    }
                ]
            },
           ...
        ]
    }
    

22.5.7 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:asc,attribute2

The following sample (URL1) fetches the Departments collection sorted by the DepartmentName attribute. The second sample (URL2) fetches the child Employees collection sorted by the salary attribute. Since the sort order flag is not specified for either request sample, the response is ascending order.

Request

  • URL 1

    http://server/demo/rest/11.0/Departments?orderBy=DepartmentName

  • URL 2

    http://server/demo/rest/11.0/Departments/50/child/Employees?orderBy=Salary

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

    none

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • Payload 1

    {
      "items" : [ {
        "DepartmentId" : 10,
        "DepartmentName" : "Administration",
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
          "name" : "Employees",
          "kind" : "collection"
        } ]
      }, {
        "DepartmentId" : 40,
        "DepartmentName" : "Human Resources",
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/40",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/40",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/40/child/Employees",
          "name" : "Employees",
          "kind" : "collection"
        } ]
      }, {
        "DepartmentId" : 20,
        "DepartmentName" : "Marketing",
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/20",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/20",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/20/child/Employees",
          "name" : "Employees",
          "kind" : "collection"
        } ]
      }, {
        "DepartmentId" : 30,
        "DepartmentName" : "Purchasing",
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/30",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/30",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/30/child/Employees",
          "name" : "Employees",
          "kind" : "collection"
        } ]
      }, {
        "DepartmentId" : 50,
        "DepartmentName" : "Shipping",
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/50",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/50",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/50/child/Employees",
          "name" : "Employees",
          "kind" : "collection"
        } ]
      } ],
      "count" : 5,
      "hasMore" : false,
      "limit" : 25,
      "offset" : 0,
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/11.0/Departments",
        "name" : "Departments",
        "kind" : "collection"
      } ]
    }
    
  • Payload 2

    {
      "items" : [ {
        "EmployeeId" : 132,
        "FirstName" : "TJ",
        "LastName" : "Olson",
        "Email" : "TJOLSON",
        "JobId" : "ST_CLERK",
        "DepartmentId" : 50,
        "Salary" : 2100,
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Employees/132",
          "name" : "Employees",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Employees/132",
          "name" : "Employees",
          "kind" : "item"
        } ]
      }, {
        "EmployeeId" : 136,
        "FirstName" : "Hazel",
        "LastName" : "Philtanker",
        "Email" : "HPHILTAN",
        "JobId" : "ST_CLERK",
        "DepartmentId" : 50,
        "Salary" : 3100,
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Employees/136",
          "name" : "Employees",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Employees/136",
          "name" : "Employees",
          "kind" : "item"
        } ]
      } ],
      "count" : 2,
      "hasMore" : false,
      "limit" : 25,
      "offset" : 0,
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/11.0/Employees",
        "name" : "Employees",
        "kind" : "collection"
      } ]
    }
    

22.6 Creating a Resource Item

ADF supports creating new items in resource collection using the HTTP method. The ADF REST runtime supports the HTTP POST method to create a resource and child resource item in REST resource collection.

The ADF REST runtime supports the following creation use cases:

  • Creating a resource item in collection.

  • Creating a child resource item.

22.6.1 Creating a Resource Item in 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"
      } ]
    }
    

22.6.2 Creating 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/child/Employees/99999

  • Payload 2

    {
      "DepartmentId" : 17,
      "DepartmentName" : "NewerDept",
      "Employees" : [ {
        "EmployeeId" : 99999,
        "FirstName" : "Newer",
        "LastName" : "Guy",
        "Email" : "NRGUY",
        "JobId" : "SA_MAN",
        "DepartmentId" : 17,
        "Salary" : 10001,
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/17/child/Employees/99999",
          "name" : "Employees",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/17/child/Employees/99999",
          "name" : "Employees",
          "kind" : "item"
        }, {
          "rel" : "parent",
          "href" : "http://server/demo/rest/11.0/Departments/17",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "lov",
          "href" : "http://server/demo/rest/11.0/Departments/17/child/Employees/99999/lov/JobsLOV",
          "name" : "JobsLOV",
          "kind" : "collection"
        } ]
      } ],
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/11.0/Departments/17",
        "name" : "Departments",
        "kind" : "item"
      }, {
        "rel" : "canonical",
        "href" : "http://server/demo/rest/11.0/Departments/17",
        "name" : "Departments",
        "kind" : "item"
      } ]
    }
    

22.7 Updating a Resource Item

ADF supports updating existing items using the HTTP method. The ADF REST runtime supports the HTTP PATCH method to update a resource in 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"
      } ]
    }
    

22.8 Deleting a Resource Item

ADF supports deleting an existing item in a resource collection using the HTTP method. The ADF REST runtime supports the HTTP DELETE method to delete a resource in 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

22.9 Checking for Data Consistency

When updating or retrieving ADF REST resource items using the HTTP method, you can check the 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"
  } ]
}

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

  1. Obtain the ETag value from the header of a GET request for the resource item:

    HTTP/1.1 200 OK
    Cache-Control: no-cache, no-store, must-revalidate
    Location:
    Content-Length: 861
    Content-Type: application/json
    ETag: "responseETag123"
    Content-Encoding:
    Link: <http://server/demo/rest/11.0/Departments/10>;rel="self";kind="item";name="Departments"
    Set-Cookie: JSESSIONID=jXvsJ1GpdkFJV5Jh0yk7D72vPZ42t8tLYDg74NRKFQzXdnsjG9vv!1113104013; path=/; HttpOnly
    X-ORACLE-DMS-ECID: 51f1ff4535af720c:-7e156247:148ec9eeb3b:-8000-00000000000001ad
    X-Powered-By: Servlet/2.5 JSP/2.1
     
    {
      "DepartmentId" : 10,
      "DepartmentName" : "Administration",
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/11.0/Departments/10",
        "name" : "Departments",
        "kind" : "item",
        "properties" : {
          "changeIndicator" : "responseETag123"
        }
      }, {
        "rel" : "canonical",
        "href" : "http://server/demo/rest/11.0/Departments/10",
        "name" : "Departments",
        "kind" : "item"
      }, {
        "rel" : "child",
        "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
        "name" : "Employees",
        "kind" : "collection"
      } ]
    }
    
  2. Make the PATCH request for the resource item and check for data consistency by supplying the following conditional header field:

    • If-Match: "<ETag value from resource item response>" to verify that the state of a requested resource item is current with the previous resource item response.

The following sample updates the DepartmentName field of the Departments 10 resource item when the If-Match precondition test is satisfied. In the first request (Request 1), the ETag value responseETag123 is identical to the ETag of the current Departments 10 resource item on the server side, indicating that the state of the resource item is consistent with the server side. Consequently, the update to DepartmentName is allowed.

In the subsequent request (Request 2), however, the ETag supplied in the If-Match precondition is unchanged and no longer matches the new ETag value the server has for the Departments 10 resource item. As a consequence of the stale ETag value used in the second request, the update fails with an HTTP code 412, indicating the precondition test failed, and the current ETag value responseETag567 is returned in the response header.

Request 1

  • URL 1

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

  • HTTP Method

    PATCH

  • Precondition 1

    If-Match: "responseETag123"

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • Payload 1

    {
      "DepartmentName" : "FirstAttempt_NewDepartmentName"
    }
    

Response 1

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • ETag

    responseETag567

  • Payload 1

    {
        "DepartmentId" : 10,
        "DepartmentName" : "FirstAttempt_NewDepartmentName",
        "RelState" : null,
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "Departments",
          "kind" : "item",
          "properties" : {
            "changeIndicator" : "responseETag567"
          }
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
          "name" : "Employees",
          "kind" : "collection"
        } ]
    }
    

Request 2

  • URL 2

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

  • HTTP Method

    PATCH

  • Precondition 2

    If-Match: "staleETag789"

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • Payload 2

    {
      "DepartmentName" : "SecondAttempt_NewDepartmentName"
    }
    

Response 2

  • HTTP Code

    412 (Precondition failed)

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • ETag

    responseETag567

  • Payload 2

    {
        "DepartmentId" : 10,
        "DepartmentName" : "FirstAttempt_NewDepartmentName",
        "RelState" : null,
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "Departments",
          "kind" : "item",
          "properties" : {
            "changeIndicator" : "responseETag567"
          }
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
          "name" : "Employees",
          "kind" : "collection"
        } ]
    }
    

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

  1. Obtain the ETag value from the header of a GET request for the resource item:

    HTTP/1.1 200 OK
    Cache-Control: no-cache, no-store, must-revalidate
    Location:
    Content-Length: 861
    Content-Type: application/json
    ETag: "responseETag123"
    Content-Encoding:
    Link: <http://server/demo/rest/11.0/Departments/10>;rel="self";kind="item";name="Departments"
    Set-Cookie: JSESSIONID=jXvsJ1GpdkFJV5Jh0yk7D72vPZ42t8tLYDg74NRKFQzXdnsjG9vv!1113104013; path=/; HttpOnly
    X-ORACLE-DMS-ECID: 51f1ff4535af720c:-7e156247:148ec9eeb3b:-8000-00000000000001ad
    X-Powered-By: Servlet/2.5 JSP/2.1
     
    {
      "DepartmentId" : 10,
      "DepartmentName" : "Administration",
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/11.0/Departments/10",
        "name" : "Departments",
        "kind" : "item",
        "properties" : {
          "changeIndicator" : "ACED0005737200136A6176612E7574696C2E4"
        }
      }, {
        "rel" : "canonical",
        "href" : "http://server/demo/rest/11.0/Departments/10",
        "name" : "Departments",
        "kind" : "item"
      }, {
        "rel" : "child",
        "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
        "name" : "Employees",
        "kind" : "collection"
      } ]
    }
    
  2. Make the GET request for the resource item and check for data consistency by supplying the following conditional header field:

    • If-None-Match: "<ETag value from resource item response>" to verify that the state of none of the previously requested resource items is current with the resource item request.

The following sample retrieves the Departments 10 resource item when the If-None-Match precondition test is satisfied. In the first request (Request 1), the ETag value responseETag123 matches the ETag of the previously requested Departments 10 resource item on the server side, indicating that the state of the resource item is consistent with the server side. Consequently, the precondition fails and there is no need to return a newer Departments 10 resource item. The request returns with an HTTP code 304, indicating the state on the server has not been modified.

In the subsequent request (Request 2), however, the ETag unmatchedETagXYZ supplied in the If-None-Match precondition does not exist on the server. As a consequence, the precondition succeeds and the Departments 10 resource item is retrieved. The request returns an HTTP code 200, indicating the state had changed, and the current (unchanged) ETag value responseETag123 is returned in the response header.

Request 1

  • URL 1

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

  • HTTP Method

    GET

  • Precondition 1

    If-None-Match: "responseETag123"

  • Content-Type

    none

  • Payload

    none

Response 1

  • HTTP Code

    304 state not modified

  • Content-Type

    none

  • Payload 1

    none

Request 2

  • URL 2

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

  • HTTP Method

    GET

  • Precondition 2

    If-None-Match: "unmatchedETagXYZ"

  • Content-Type

    none

  • Payload

    none

Response 2

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • ETag

    responseETag123

  • Payload 2

    {
        "DepartmentId" : 10,
        "DepartmentName" : "Administration",
        "RelState" : null,
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "Departments",
          "kind" : "item",
          "properties" : {
            "changeIndicator" : "responseETag123"
          }
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.0/Departments/10",
          "name" : "Departments",
          "kind" : "item"
        }, {
          "rel" : "child",
          "href" : "http://server/demo/rest/11.0/Departments/10/child/Employees",
          "name" : "Employees",
          "kind" : "collection"
        } ]
    }
    

22.10 Working with Attachments

The ADF REST runtime supports content streaming of the custom content that is not contained in payload by using a link to the content. You can create LOB content at the same time 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

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

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

  2. Execute an HTTP operation (GET or DELETE) using the link to the LOB content.

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

{
  "EmployeeId" : 101,
  "FirstName" : "Neena",
  "LastName" : "Smith",
  "Email" : "NSMITH",
  "JobId" : "AD_VP",
  "DepartmentId" : 90,
  "Salary" : 2000,
  "links" : [ {
    "rel" : "self",
    "href" : "http://server/demo/rest/11.0/Employees/101",
    "name" : "Employees",
    "kind" : "item"
  }, {
    "rel" : "canonical",
    "href" : "http://server/demo/rest/11.0/Employees/101",
    "name" : "Employees",
    "kind" : "item"
  }, {
    "rel" : "lov",
    "href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV",
    "name" : "JobsLOV",
    "kind" : "collection"
  }, {
    "rel" : "enclosure",
    "href" : "http://server/demo/rest/11.0/Employees/101/enclosure/Picture",
    "name" : "Picture",
    "kind" : "other"
  } ]
}

For example, the following sample streams the PNG image associated with employee 101.

Note that by default the request type is application/octet-stream to support a variety of media types. If the ADF REST resource developer defined the custom property contentType, the specified request type appears in the resource item describe.

Request

  • URL

    http://server/demo/rest/11.0/Employees/101/enclosure/Picture

  • HTTP Method

    GET

  • Content Type

    none

  • Payload

    none

Response

  • HTTP Code

    200

  • Content-Type

    image/png

  • Payload

    content streamed

22.10.2 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"
      } ]
    }
    

22.11 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 LOV-enabled attributes use cases:

  • Retrieving LOV attribute values in the context of an existing resource item.

    Refer to this use case when you need to allow users to update an existing resource item and the resource item defines an LOV-enabled attribute.

  • Retrieving LOV attribute values when no context for an existing resource item exists.

    Refer to this use case when you need to create a resource item and that resource item defines an LOV-enabled attribute.

22.11.1 Retrieving LOV-Enabled Attribute Values for Existing Resource Items

The ADF REST runtime supports retrieving the values from LOV-enabled attributes using a GET method on an existing resource item.

An existing resource item for an LOV-enabled attribute nests an LOV child resource that you can use to obtain the list of values that is appropriate based on the context of the containing resource item.

When you create a new resource item and need to retrieve LOV values, you access an LOV resource that is not nested inside the resource collection. For details about accessing a non-nested LOV resource, see Retrieving LOV-Enabled Attribute Values When Creating a Resource Item.

To work with LOV-enabled attributes on existing resource items:

  1. Execute the resource describe and locate the following details about the LOV:

    Under the lov description of a resource attribute, locate the childRef property to identify the child resource collection that contains the LOV choices.

    The lov description contains the view object attribute mapping from the resource item to the LOV child resource collection. The attribute mapping contains one or more source attributes from the child resource whose values will be copied to the resource item when an LOV value is selected. An LOV selection could derive more values in the resource item besides the attribute displaying the LOV. In such cases, the attribute mapping will identify it as derived = true. Finally, the lov description identifies which attributes from the child resource collection could be used for displaying to end users if the results are bound to a user interface.

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

  3. Execute a GET using the LOV link and, optionally, use additional filtering to narrow down the LOV results or to exclude not needed attributes from the payload. You should always fetch the display attributes listed in the lov description. The display attribute is the attribute value that allows the end user to make an LOV value selection from a list of values that they would recognize (such as the list of job titles). The LOV definition ensures that the correct source attribute is used to update the resource item when the LOV selection is applied.

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

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

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

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

Request

  • URL

    http://server/demo/rest/11.0/Employees/101/lov/JobsLOV?onlyData=true&fields=JobTitle

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.resourcecollection+json

  • Payload

    {
      "items" : [ {
        "JobTitle" : "President"
      }, {
        "JobTitle" : "Administration Assistant"
      }, {
        "JobTitle" : "Finance Manager"
      }, {
        "JobTitle" : "Accountant"
      }, {
        "JobTitle" : "Accounting Manager"
      }, {
        "JobTitle" : "Public Accountant"
      } ],
      "count" : 6,
      "hasMore" : false,
      "limit" : 25,
      "offset" : 0,
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/11.0/Employees/101/lov/JobsLOV",
        "name" : "JobsLOV",
        "kind" : "collection"
      } ]
    }
    

22.11.2 Retrieving LOV-Enabled Attribute Values When Creating a Resource Item

The ADF REST runtime supports retrieving the values from LOV-enabled attributes using a GET method when it is necessary to create a new resource item that does not exist in the resource collection.

For an already existing resource item, use the resource item link to access the LOV child resource that has been defined for the particular item. For details about accessing the LOV child resource, see Retrieving LOV-Enabled Attribute Values for Existing Resource Items.

To work with LOV-enabled attributes when creating a resource item:

  1. Execute the resource describe and locate the following details about the LOV:

    Under the lov description of an attribute, locate the lovResourcePath property to identify the LOV resource that contains the LOV choices.

    The lov description contains the attribute mapping from the resource item to the LOV resource collection. The attribute mapping contains one or more source attributes from the LOV resource whose values will be copied to the resource item when an LOV value is selected. An LOV selection could derive more values in the resource item besides the attribute displaying the LOV. In such cases, the attribute mapping will identify it as derived = true. Finally, the lov description identifies which attributes from the LOV resource collection could be used for displaying to end users if the results are bound to a user interface.

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

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

  4. With the cached LOV attribute values from the LOV resource, it is then possible to display the LOV display attribute in the client user interface where the end user is expected to enter values to create a new resource item. When enters the desired values, chooses a value from the displayed LOV for the LOV-enabled attribute, and then clicks Submit, the client can execute the create request. The ADF Business Components view object attribute's LOV definition ensures that the correct source attribute is used to update the resource item when the LOV selection is applied. For details about submitting a POST request with the payload that creates a new resource item, see Creating a Resource Item in Collection.

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

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

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

Request

  • URL

    http://server/demo/rest/11.0/Jobs?onlyData=true&fields=JobTitle

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.resourcecollection+json

  • Payload

    {
      "items" : [ {
        "JobTitle" : "President"
      }, {
        "JobTitle" : "Administration Assistant"
      }, {
        "JobTitle" : "Finance Manager"
      }, {
        "JobTitle" : "Accountant"
      }, {
        "JobTitle" : "Accounting Manager"
      }, {
        "JobTitle" : "Public Accountant"
      } ],
      "count" : 6,
      "hasMore" : false,
      "limit" : 25,
      "offset" : 0,
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/11.0/Jobs",
        "name" : "Jobs",
        "kind" : "collection"
      } ]
    }
    

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

{
    "items" : [
        {
            "version" : "11.2",
            "isLatest" : true,
            "adf:extension" : {
                    "defaultFrameworkVersion" : "2",
            },
            "links" : [
             ...

For details about the ADF REST framework functionality supported in each framework version, see What You May Need to Know About Versioning the ADF REST Runtime Framework.

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

  1. Execute the service end point describe and locate the available release version names in the describe.

  2. Locate the version property to identify the release version.

  3. Examine the associated defaultFrameworkVersion property to understand the version of the ADF REST framework that will be used to execute requests for the specific release version.

For example, the describe for a service end point with two release versions returns the following objects, where each release version has been associated with a specific ADF REST framework version:

{
    "items" : [
        {
            "version" : "version_identifier_latest",
            "isLatest" : true,
            "adf:extension" : {
                    "defaultFrameworkVersion" : "framework_identfier",
            },
            "links" : [
                {
                    "rel" : "self",
                    ...
 
                },
                {
                    "rel" : "canonical",
                    ...
 
                },
                {
                    "rel" : "predecessor-version",
                    ...
 
                },
                {
                    "rel" : "describe",
                    ...
 
                }
            ]
        },
        {
            "version" : "version_identifier_previous",
            "adf:extension" : {
                    "defaultFrameworkVersion" : "framework_identfier",
            },
            "links" : [
                {
                    "rel" : "self",
                    ...
                },
                {
                    "rel" : "canonical",
                    ...
                },
                {
                    "rel" : "successor-version",
                    ...
                },
                {
                    "rel" : "describe",
                    ...
                }
            ]
        }
    ],
    "links" : [
     ...
        {
            "rel" : "current",
                    ...
        }
    ]
}

The following sample retrieves all available release versions defined in the resource catalog of the demo application. In the sample, the three release versions are 11.0, 11.1, and 11.2, where 11.2 is the current (or most recent) release version. In the sample, versions 11.0 and 11.1 are explicitly associated with ADF REST framework version 1 and release version 11.2 is associated with ADF REST framework version 2. Note that a framework version refers to a specific version of the ADF REST framework, available starting in a particular Oracle JDeveloper release.

Request

  • URL

    http://server/demo/rest

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

    none

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.description+json

  • Payload

    {
        "items" : [
            {
                "version" : "11.2",
                "isLatest" : true,
                "adf:extension" : {
                        "defaultFrameworkVersion" : "2",
                },
                "links" : [
                    {
                        "rel" : "self",
                        "href" : "http://server/demo/rest/11.2",
                        "name" : "self",
                        "kind" : "item"
                    },
                    {
                        "rel" : "canonical",
                        "href" : "http://server/demo/rest/11.2",
                        "name" : "canonical",
                        "kind" : "item"
                    },
                    {
                        "rel" : "predecessor-version",
                        "href" : "http://server/demo/rest/11.1",
                        "name" : "predecessor-version",
                        "kind" : "item"
                    },
                    {
                        "rel" : "describe",
                        "href" : "http://server/demo/rest/11.2/describe",
                        "name" : "describe",
                        "kind" : "describe"
                    }
                ]
            },
            {
                "version" : "11.1",
                "adf:extension" : {
                        "defaultFrameworkVersion" : "1",
                },
                "links" : [
                    {
                        "rel" : "self",
                        "href" : "http://server/demo/rest/11.1",
                        "name" : "self",
                        "kind" : "item"
                    },
                    {
                        "rel" : "canonical",
                        "href" : "http://server/demo/rest/11.1",
                        "name" : "canonical",
                        "kind" : "item"
                    },
                    {
                        "rel" : "predecessor-version",
                        "href" : "http://server/demo/rest/11.0",
                        "name" : "predecessor-version",
                        "kind" : "item"
                    },
                    {
                        "rel" : "successor-version",
                        "href" : "http://server/demo/rest/11.2",
                        "name" : "successor-version",
                        "kind" : "item"
                    },
                    {
                        "rel" : "describe",
                        "href" : "http://server/demo/rest/11.1/describe",
                        "name" : "describe",
                        "kind" : "describe"
                    }
                ]
            },
            {
                "version" : "11.0",
                "adf:extension" : {
                        "defaultFrameworkVersion" : "1",
                },
                "links" : [
                    {
                        "rel" : "self",
                        "href" : "http://server/demo/rest/11.0",
                        "name" : "self",
                        "kind" : "item"
                    },
                    {
                        "rel" : "canonical",
                        "href" : "http://server/demo/rest/11.0",
                        "name" : "canonical",
                        "kind" : "item"
                    },
                    {
                        "rel" : "successor-version",
                        "href" : "http://server/demo/rest/11.1",
                        "name" : "successor-version",
                        "kind" : "item"
                    },
                    {
                        "rel" : "describe",
                        "href" : "http://server/demo/rest/11.0/describe",
                        "name" : "describe",
                        "kind" : "describe"
                    }
                ]
            }
        ],
        "links" : [
            {
                "rel" : "self",
                "href" : "http://server/demo/rest",
                "name" : "self",
                "kind" : "collection"
            },
            {
                "rel" : "canonical",
                "href" : "http://server/demo/rest",
                "name" : "canonical",
                "kind" : "collection"
            },
            {
                "rel" : "current",
                "href" : "http://server/demo/rest/11.2",
                "name" : "current",
                "kind" : "item"
            }
        ]
    }
    

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

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

22.13 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,, count of resource items in a resource collection, query a resource with filter, and retrieve 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.

  • Executing a custom action defined by view object client interface.

  • Overriding the HTTP method to perform an update

  • Making batch requests.

22.13.1 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"
            }
        ]
    }
    

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

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

  2. 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"
      } ]
    }
    

22.13.3 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"
      } ]
    }
    

22.13.4 Returning the Estimated Count of Resource Items

The ADF REST runtime supports retrieving the estimated number of resource items in resource collections using a GET method.

The following sample returns an estimated total result of 5 for the Employees collection. The query parameter totalResults ensures the response payload contains the totalResults attribute.

Request

  • URL

    http://server/demo/rest/11.1/Employees?totalResults=true&limit=2

  • HTTP Method

    GET

  • Content-Type

    none

  • Payload

    none

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.resourceitem+json

  • Payload

    {
      "items" : [ {
        "EmployeeId" : 101,
        "FirstName" : "Neena",
        "LastName" : "Smith",
        "Email" : "NSMITH",
        "JobId" : "AD_VP",
        "DepartmentId" : 90,
        "Salary" : 2000,
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.1/Employees/NSMITH",
          "name" : "Employees",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.1/Employees/NSMITH",
          "name" : "Employees",
          "kind" : "item"
        }, {
          "rel" : "lov",
          "href" : "http://server/demo/rest/11.1/Employees/NSMITH/lov/JobsLOV",
          "name" : "JobsLOV",
          "kind" : "collection"
        } ]
      }, {
        "EmployeeId" : 102,
        "FirstName" : "Lex",
        "LastName" : "De Haan",
        "Email" : "LDEHAAN",
        "JobId" : "AD_VP",
        "DepartmentId" : 90,
        "Salary" : 3000,
        "links" : [ {
          "rel" : "self",
          "href" : "http://server/demo/rest/11.1/Employees/LDEHAAN",
          "name" : "Employees",
          "kind" : "item"
        }, {
          "rel" : "canonical",
          "href" : "http://server/demo/rest/11.1/Employees/LDEHAAN",
          "name" : "Employees",
          "kind" : "item"
        }, {
          "rel" : "lov",
          "href" : "http://server/demo/rest/11.1/Employees/LDEHAAN/lov/JobsLOV",
          "name" : "JobsLOV",
          "kind" : "collection"
        } ]
      } ],
      "totalResults" : 5,
      "count" : 2,
      "hasMore" : true,
      "limit" : 2,
      "offset" : 0,
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/11.1/Employees",
        "name" : "Employees",
        "kind" : "collection"
      } ]
    }
    

22.13.5 Executing a Custom Action

The ADF REST runtime supports executing one or more custom actions that have been defined on the client interface of the resource's backing view object using a POST method.

The following sample executes the custom action multiplySalary on an instance of the Employees collection. In this case, the custom action has been defined on the view row client interface for the backing view object and therefore enables executing actions on row-level instances.

Request

  • URL

    http://server/demo/rest/11.1/Employees/101

  • HTTP Method

    POST

  • Content-Type

    application/vnd.oracle.adf.action+json

  • Payload

    {
        "name": "multiplySalary",
        "parameters": [
            {
                  "multiplicand": "2"
             }
        ]
    }
    

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.actionresult+json

  • Payload

    {
      "result" : 4000.0
    }
    

22.13.6 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"
      } ]
    }
    

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

The following sample illustrates a successful batch operation that executes operations in three parts.

Request

  • URL

    http://server/demo/rest

  • HTTP Method

    POST

  • Content-Type

    application/vnd.oracle.adf.batch+json

  • Payload

    {
        "parts": [
            {
                "id": "part1",
                "path": "/11.1/Employees/101",
                "operation": "update",
                "payload": {
                    "Salary": 10000
                }
            },
            {
                "id": "part2",
                "path": "/11.1/Employees/102",
                "operation": "update",
                "payload": {
                    "Salary": 10000
                }
            },
            {
                "id": "part3",
                "path": "/11.1/Employees/103",
                "operation": "update",
                "payload": {
                    "Salary": 10000
                }
            }
        ]
    }
    

Response

  • HTTP Code

    200

  • Content-Type

    application/vnd.oracle.adf.batch+json

  • Payload

    {"parts": {
          {
            "id" : "part1",
            "path" : "/11.1/Employees/101",
            "operation" : "update",
            "payload" : {
                "EmployeeId" : 101,
                "FirstName" : "Neena",
                "LastName" : "Smith",
                "Email" : "NSMITH",
                "JobId" : "AD_VP",
                "DepartmentId" : 90,
                "Salary" : 10000,
            "links" : [ {
                 "rel" : "self",
                 "href" : "http://server/demo/rest/11.1/Employees/101",
                 "name" : "Employees",
                 "kind" : "item"
            }, {
                 "rel" : "canonical",
                 "href" : "http://server/demo/rest/11.1/Employees/101",
                 "name" : "Employees",
                 "kind" : "item"
            }, {
                 "rel" : "lov",
                 "href" : "http://server/demo/rest/11.1/Employees/101/lov/JobsLOV",
                 "name" : "JobsLOV",
                 "kind" : "collection"
            } ]
            }
          }, {
            "id" : "part2",
            "path" : "/11.1/Employees/102",
            "operation" : "update",
            "payload" : {
                "EmployeeId" : 102,
                "FirstName" : "Lex",
                "LastName" : "De Haan",
                "Email" : "LDEHAAN",
                "JobId" : "AD_VP",
                "DepartmentId" : 90,
                "Salary" : 10000,
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.1/Employees/102",
              "name" : "Employees",
              "kind" : "item"
             }, {
              "rel" : "canonical",
              "href" : "http://server/demo/rest/11.1/Employees/102",
              "name" : "Employees",
              "kind" : "item"
            }, {
              "rel" : "lov",
              "href" : "http://server/demo/rest/11.1/Employees/102/lov/JobsLOV",
              "name" : "JobsLOV",
              "kind" : "collection"
            } ]
            }
          }, {
            "id" : "part3",
            "path" : "/11.1/Employees/103",
            "operation" : "update",
            "payload" : {
                "EmployeeId" : 103,
                "FirstName" : "Alexander",
                "LastName" : "Hunold",
                "Email" : "AHUNOLD",
                "JobId" : "IT_PROG",
                "DepartmentId" : 60,
                "Salary" : 10000,
            "links" : [ {
              "rel" : "self",
              "href" : "http://server/demo/rest/11.1/Employees/103",
              "name" : "Employees",
              "kind" : "item"
            }, {
              "rel" : "canonical",
              "href" : "http://server/demo/rest/11.1/Employees/103",
              "name" : "Employees",
              "kind" : "item"
            }, {
              "rel" : "lov",
              "href" : "http://server/demo/rest/11.1/Employees/103/lov/JobsLOV",
              "name" : "JobsLOV",
              "kind" : "collection"
            } ]
          }
          } ]
    }
    

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

22.14.1 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-3 describes the content-encoding tokens supported by the ADF REST framework.

Table 22-3 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].

22.14.2 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-4. The types are defined such that the media type does not vary with the view object definition backing the resource. Note that the value of the accept header depends on the context of the invocation. Links to the JSON token structure of the ADF REST framework media types are provided in the following table.

Note:

As an alternative to specifying the supported media types, the service client request accept header can specify application/json when a superset of all supported media types may be accepted in the response.

Table 22-4 Media Types Supported by the ADF REST Framework

Media Type Invocation Context Description

application/vnd.oracle.adf.resourcecollection+json

GET method

POST method

Represents the format for all resource collections returned by the ADF REST runtime.

All attributes are automatically generated by the framework. Only the content of the 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

DELETE method

PATCH method

Represents the format for all resource items returned by the ADF REST runtime.

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.action+json

POST method

Describes custom action execution and their parameters.

Exposed custom actions are backed by methods of a view object interface or view row interface.

For an example, see Executing a Custom Action.

application/vnd.oracle.adf.actionresult+json

POST method

Describes the result of an action execution.

For an example, see Executing a Custom Action.

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.

22.14.3 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-5 shows the relationship between the ADF Business Components data types supported on entity object attributes backing the view object of ADF REST resources and the corresponding ADF REST data types that the ADF REST framework defines. In general, the framework defines the data type of an ADF REST resource item based on the SQL type of the attribute backing the resource item, with these two exceptions:

  • When the backing attribute is defined as a boolean type map, then the ADF REST type will always be a boolean.

  • When the backing attribute’s Java type is blob or clob, then the ADF REST type will be an attachment.

Table 22-5 Data Types Supported by the ADF REST Framework

ADF Backing Attribute ADF REST Data Type

Where an attribute is configured with one of the following type maps:

oracle.jbo.valuemaps.Boolean10PropertySet

oracle.jbo.valuemaps.BooleanTFPropertySet

oracle.jbo.valuemaps.BooleanYNPropertySet

boolean

Java Class: oracle.jbo.domain.ClobDomain or

oracle.jbo.domain.BlobDomain

Note that in a future release the SQL type will be used instead of the Java Class.

attachment
SQL type: Char string
SQL type: Number

integer

Note that in a future release this ADF REST type will change to number because the number of digits is not specified.

SQL type: Number (precision = *, scale > 0) number
SQL type: Number (precision < 10, scale = 0) integer
SQL type: Number (precision >= 10, scale = 0)

integer

Note that in a future release this ADF REST type will change to number because integers may not have more than 9 digits.

SQL type: Date and Timestamp

date and datetime

22.14.4 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-6 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.

22.14.5 ADF REST HTTP Headers Support

The ADF REST framework supports the HTTP headers listed in the following table.

Table 22-7 HTTP Headers Supported by the ADF REST Framework

HTTP Header Name Description

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.

Cache-Control

Use to avoid intermediate proxies to cache/store framework payloads. This header is configured for every HTTP response. Valid values are: no-cache, no-store, must-revalidate.

It can either be set application-wide by specifying it as an init-param in the web.xml file. The value set in the init-param will override the default.

In case finer control is needed, the value can be set on the resource tree and the header will be set accordingly. Currently, Cache-Control can be configured only as “max-age: ..”, 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". This value is set in the Cache-Control header in the response for an operation involving any resource belonging to the resource tree.

Please note that this resource definition value will override the default setting and the setting made by the init-param in the web.xml file. Further, if configured on the resource definition, the Cache-Control value is also shown in the describe, per resource. Note that clients could use this information to further customize the caching mechanism at their end; where it would be especially useful for batch requests.

22.14.6 ADF REST HTTP Method and Payload Support

The ADF REST framework supports operations on the following HTTP methods.

  • GET

  • POST

  • PATCH

  • DELETE

22.14.6.1 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, the latest resource version, or all available resources (when version identifier and resource collection are omitted).

    http://server/demo/rest/[{version}|latest/{resourceCollectionPath}]
    

Request Parameters

  • The GET method supports query string parameters to query, filter, page, and sort the resource representation. The supported parameters are listed in the following table. All GET method URI parameters can be combined with any other parameter in the table, except where noted on the expand and field parameters. Note that query string parameters can only be used on resource media types. They cannot, for example, be used when describing the resource.

Table 22-8 Supported Resource Media Type GET Method Query String Parameters

GET URI Parameter Resource Type (Item | Collection) Value Description

q “query by example” syntax

Supported only in the base version of ADF REST framework, version 1. See the next row for a description of q parameter support offered in framework version 2 (and later).

For additional information about framework versions, see What You May Need to Know About Versioning the ADF REST Runtime Framework.

resource collections only

One or more query by example-type expressions, separated by semi-colons.

Format: <exp1>;<exp2>

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

The resource collection will be queried using the provided expressions.

Supported operators:

  • Greater than: >

  • Less than: <

  • Greater than or equal to: >=

  • Less than or equal to: <=

  • Null : IS NULL

  • Not null: IS NOT NULL

  • And: AND

  • Or: OR

  • Equals: =

  • Like: LIKE

Special Characters:

  • Define literals: " or ' (double or single quote)

  • Escape: \

  • Wildcard: *

For an example of the usage supported in ADF REST framework version 1, see Filtering a Resource Collection with a Query Parameter.

q rowmatch expressions

Supported in ADF REST framework version 2 and later.

Note that this syntax requires the service client to use ADF REST framework version 2 or later.

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

resource collections only

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%'))

For complete an explanation of the rowmatch expression format, see What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2.

The resource collection will be queried using the provided expressions.

Supported operators:

  • Greater than: >

  • Less than: <

  • Greater than or equal to: >=

  • Less than or equal to: <=

  • Equal to: =

  • Not equal to: <>

  • Null : IS NULL

  • Not null: IS NOT NULL

  • And: AND

  • Or: OR

  • Between: BETWEEN

  • Not between: NOT BETWEEN

  • Like: LIKE

  • In: IN

Special Characters:

  • Define literals: " or ' (double or single quote)

  • Escape: \

  • Wildcard: %

For an example of rowmatch usage in ADF REST framework version 2, see Filtering a Resource Collection with a Query Parameter.

For additional examples of rowmatch expressions, see What You May Need to Know About the Advanced Query Syntax in ADF REST Framework Version 2.

finder

resource collections only

An expression containing information about the finder and its parameters.

Format: <finder>;<param1>=<val1>,<param2>=<value2>

Example: ?finder=DeptByName;Dname=ACCOUNTING

The resource collection will be queried using the provided finder/parameter. The list of available finders is provided in the describe.

Finders with parameters whose type does not belong to char, date, or number, will be filtered out.

For an example, see Filtering a Resource Collection with a Row Finder.

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.

both

A simple comma separate list of resource item attributes.

Format: <attr1>,<attr2>

Example: ?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=Employees:FirstName;Employees.JobHistory:JobId

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

both

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.

totalResults

resource collections only

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.

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.

both

Display all children. Format: all

Display more than one child resource using a comma separate 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.

limit

resource collections only

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

resource collections only

integer

Default: 0 (the first position)

Used to define the starting position of the resource collection. If offset exceeds the resource count, then no resources are returned.

For an example, see Paging a Resource Collection.

dependency

both

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

both

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: ?DName:asc,DLoc

Default: ORDERBY attributes defined on the view object query backing the resource will be applied.

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

For an example, see Sorting a Resource Collection.

links

both

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.

include

Resource Catalog Describe

A comma separated list of <visibility_type>, where <visibility_type> can be all, unlisted, or public.

When a resource catalog describe is requested and the include query parameter is used with one or more visibility types specified, then only those resources with a Visibility property matching a value in the comma-separated parameter value will be shown in the response.

Note top-level resources can be hidden from a catalog describe by setting the Visibility property in the <ServiceConfiguration> tag on the resource definition. The following sample of a resource definition file shows how to set the property.

<pageDefinition ...>
  <parameters/>
  <executables/>
  <bindings>
    <tree ....>
      <ServiceConfiguration Visibility="unlisted"/>
      <nodeDefinition ../>
    </tree>
  </bindings>
</pageDefinition>

includeChildren

Resource Item Describe

boolean

Default: false

Example: ?includeChildren=true

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 and Describing a Nested Resource.

Query String Operators Supported by ADF REST Data Types

The following table shows the ADF REST data types and the valid operators that may be used in query parameter strings. Note that the operators BETWEEN, NOT BETWEEN, IN, NOT IN, and the wildcard character % are available only starting in ADF REST framework version 2.

Table 22-9 Operators Supported by Data Types in Query (q) Parameter Strings

ADF REST Data Type Supported Operator
integer
  • = (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
  • = (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’

  • <> ’true’ (false)

    .../Employees?q=Active <> ’true’

  • <> ’false’ (true)

    .../Employees?q=Active <> ’false’

  • = ’Y’ (true)

    .../Employees?q=Active = ’Y’

  • = ’N’ (false)

    .../Employees?q=Active = ’N’

  • = true (true)

    .../Employees?q=Active = true

  • = false (false)

    .../Employees?q=Active = false

22.14.6.2 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}
    
  • Execute an action on a resource collection or resource item.

    http://server/demo/rest/{version}/{resourceCollectionPath}|{resourceItemPath}
    
  • Execute an a batch request.

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

Request Parameters

  • none

Media Types Supported

  • Request

    • application/vnd.oracle.adf.resourceitem+json: When creating a resource or overriding the HTTP method to perform an update.

    • application/vnd.oracle.adf.action+json: When executing an action.

    • application/vnd.oracle.adf.batch+json: When executing a batch request.

  • Response

    • application/vnd.oracle.adf.resourceitem+json: When executing an action or creating a resource.

    • application/vnd.oracle.adf.actionresult+json: When executing an action that has an object to return.

    • application/vnd.oracle.adf.batch+json: When executing an batch request.

Use Case Samples

22.14.6.3 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

22.14.6.4 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