15 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 framework 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:
15.1 About the ADF REST Framework
The ADF REST framework is an ADF Model framework that allows Fusion web application developers to expose a Web API based on the REST architectural style. The framework itself does not constitute a Web API, but supports creating and interacting with resources and RESTful web services based on ADF Business Components business objects. A consequence of being RESTful, is a REST API that allows client application developers to interact with exposed business objects.
In the Fusion web application, ADF REST resources acted on by RESTful web services are backed by view object instances exposed in the data model of the ADF Business Components Model project. ADF Business Components developers working in the ADF Model project can decide on the set of attributes to expose from backing view objects, the actions to make 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 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.
15.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.
-
Interacting with the REST resource using standard HTTP request methods, including GET, POST, PUT, 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.
-
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:
-
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.
15.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.
-
For details about ADF Business Components and creating an ADF Business Components Model project, see Section 3.3, "Overview of Design Time Facilities."
-
For details about creating RESTful web services in the ADF Business Components project, including enabling LOV links, row finders, custom methods, canonical resources, change indicators, custom content types for LOB attributes, and security, see
Chapter 12, "Creating RESTful Web Services with Application Modules."
15.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 and EMPLOYEES tables in the Oracle HR schema.
15.1.3.1 Sample Project Files and Data Model
As Figure 15-1 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 deploying resources.
As Figure 15-2 shows, the data model exposes the following view instances and relationships for the DEPARTMENTS and EMPLOYEES tables.
15.1.3.2 Sample Project Resources and Resource Version Identifiers
As Figure 15-3 shows, the Departments resource is backed by the DepartmentsView view object and the child resource Employees is enabled. The JobsLOV LOV accessor defined for the EmployeesView view object is also exposed in the resource representation.
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.
As Figure 15-4 shows, the Employees root resource is backed by the EmployeesView view object. Because Employees was created as root resource, it has no child resource accessors. The LOV accessor defined for the EmployeesView view object is also exposed in the resource representation.
As Figure 15-5 shows, several version identifiers were created to support maintaining different version of the Employees resource: one with a subset of attributes and another with a more complete set of attributes.
Note that the order of the identifiers determines the version sequence, with the most recent version appearing at the top of the list. In the REST samples, resources with the identifier v2 are the latest version.
15.1.3.3 Entity Object and View Object Customization
As Figure 15-6 shows, the EmployeesView view object defines the LOV-enabled attribute JobId. The LOV accessor returns the list of jobs by title, and presents them as choices for the corresponding job ID.
As Figure 15-7 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).
As Figure 15-8 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.
As Figure 15-9 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.
Note that once defined in the view object definition, custom methods will be exposed by default on the resource.
As Figure 15-10 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.
15.2 Understanding ADF Business Components Resources
RESTful web services that service developers create in the ADF Business Components model project are based on the view objects that the project defines. 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 15-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 Section 15.13.2, "ADF REST Media Types."
15.3 Retrieving the ADF REST Resource Describe
The describe for the RESTful web service allows you to identify the shape and actions allowed on an ADF RESTful web service. It returns a JSON object that contains the attributes, actions, and links defined in the REST resource definition.
The ADF REST framework supports the following describe use cases:
-
Describe all available resources (catalog) for the application end point.
-
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.
For example, the following URL returns the describe for the Employees resource of version v1 in the identified application:
http://host:port/context-root/rest/v1/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 v1 in the identified application:
http://host:port/context-root/rest/v1/describe
15.3.1 Describing All Available Resources
ADF REST framework supports describing all available resources for the application end point using a GET method.
To examine all available resources in the resource catalog:
-
Execute the resource catalog describe and locate the names of the resources in the describe. The
childrenattribute identifies nested resources. -
Examine these resource objects to understand the shape of each resource:
-
attributesspecifies the list of available resource collection attributes. -
collectionspecifies the shape of the collection and specifiesfinderfor row finder,links, and availableactions(including media types). -
itemspecifies the shape of the instances of the collection and itself specifieslinksand availableactions. -
childrenspecifies any nested resources (and itself containsattributes,collection, anditemobjects).
-
For example, the describe for a service with Departments and child Employees resources returns the following objects:
{
"Resources" : {
"Employees" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Departments"
...
} ],
...
"links" : [ {
} ]
}
}
The following sample describes version v1 of all resources in the resource catalog. Note that the URL parameter v1 may be replaced with an application-specific version identifier. For more details about specifying resource versions, see in Section 15.9, "Versioning the Resource."
-
URL
http://server/demo/rest/v1/describe -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/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/v1/Employees/{id}/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" }, { "rel" : "self", "href" : "http://server/demo/rest/v1/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/v1/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/v1/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/v1/Employees/{id}/child/JobsLOV/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/Employees/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/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/v1/Employees/{id}/child/JobsLOV/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Employees/{id}/child/JobsLOV/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/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/v1/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/v1/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/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/v1/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/v1/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/v1/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/v1/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }
15.3.2 Describing a Resource Collection
ADF REST framework supports describing resource collections using a GET method.
To examine a resource collection:
-
Execute the resource collection describe and locate the names of the resources in the describe.
-
Examine these resource objects to understand the shape of each resource:
-
attributesspecifies the list of available resource collection attributes. -
collectionspecifies the shape of the collection and specifiesfinderfor row finder,links, and availableactions(including media types). -
itemspecifies the shape of the instances of the collection and itself specifieslinksand availableactions. -
childrenspecifies any nested resources (and itself containsattributes,collection, anditemobjects).
-
For example, the describe for the Departments resource returns the following objects:
{
"Resources" : {
"Departments" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Employees"
...
} ],
...
"links" : [ {
} ]
}
}
The following sample describes version v1 of the Departments resource.
-
URL
http://server/demo/rest/v1/Departments/describe -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/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/v1/Departments/{id}/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/{id}", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/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/v1/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/v1/Departments/{id}/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/Departments/{id}", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/{id}/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/v1/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/v1/Departments/{id}/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/{id}/child/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/describe", "name" : "canonical", "kind" : "describe" } ] } } }
15.3.3 Describing a Resource Item
ADF REST framework supports describing a resource item using a GET method.
Note that a resource item describe typically provides the same information as the collection describe. In the case of a polymorphic collection, however, a resource item describe will have more information than a resource collection describe. Consider, for example, the polymorphic collection vehicles, where the vehicles resource contains an item automobile and an item airplane. The description of vehicles will return a general shape of all vehicles, whereas, a resource item describe of an automobile will return the specific shape of that object.
To examine a resource item:
-
Execute the resource item describe and locate the names of the resources in the describe. The
childrenattribute identifies nested resources. -
Examine the resource item describe to understand its shape.
-
attributesspecifies the list of available resource collection attributes. -
itemspecifieslinksto the item, including defined child collections, and availableactions. -
linksspecifies describe links.
-
For example, the describe for a Departments resource item returns the following objects:
{
"Resources" : {
"Departments" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"links" : [ {
} ]
}
}
The following sample describes version v1 of an instance of the Departments resource collection.
-
URL
http://server/demo/rest/v1/Departments/10/describe -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection", "cardinality" : { "value" : "1 to *", "sourceAttributes" : "DepartmentId", "destinationAttributes" : "DepartmentId" } }, { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/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/v1/Departments/10/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10/describe", "name" : "canonical", "kind" : "describe" } ] } } }
15.3.4 Describing a Nested Resource
ADF REST framework supports describing an ADF REST nested resource using a GET method.
To examine nested resources in the resource catalog:
-
Execute the nested resource describe and locate the names of the resources in the describe. The
childrenattribute identifies nested resources. -
Examine these resource objects to understand the shape of each resource:
-
attributesspecifies the list of available resource collection attributes. -
collectionspecifies the shape of the collection and specifiesfinderfor row finder,links, and availableactions(including media types). -
itemspecifies the shape of the instances of the collection and itself specifieslinksand availableactions. -
childrenspecifies the nested resources (and itself containsattributes,collection, anditemobjects).
-
For example, the describe for the nested resources Departments and Employees returns the following objects:
{
"Resources" : {
"Employees" : {
"discrColumnType" : false,
"attributes" : [ {
...
} ],
"collection" : {
...
} ],
"finders" : [ {
} ]
"links" : [ {
} ]
"actions" : [ {
} ]
},
"item" : {
"links" : [ {
} ]
"actions" : [ {
} ]
},
"children" : {
"Departments"
...
} ],
...
"links" : [ {
} ]
}
}
The following sample (URL1) describes version v1 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.
-
URL 1
http://server/demo/rest/v1/Departments/10/child/Employees/describe -
URL 2
http://server/demo/rest/v1/Departments/10/child/Employees/200/describe -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/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/v1/Departments/10/child/Employees/{id}", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees/{id}", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/v1/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/v1/Departments/10/child/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/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/v1/Departments/10/child/Employees/200", "name" : "self", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "parent", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees/200", "name" : "canonical", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/v1/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/v1/Departments/10/child/Employees/200/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees/200/describe", "name" : "canonical", "kind" : "describe" } ] } } }
15.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/v1/Departments/{id}/child/Employees",
"name" : "Employees",
"kind" : "collection",
"cardinality" : {
"value" : "1 to *",
"sourceAttributes" : "DepartmentId",
"destinationAttributes" : "DepartmentId"
}
15.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 15-2.
Table 15-2 Link Relationship in ADF REST Resource Describe
| Link Relationship | Description |
|---|---|
|
|
Always generated for a resource. The |
|
|
Always generated. The |
|
|
Always generated for a nested resource. The |
|
|
Generated when the resource has nested children. The |
|
|
Generated when the resource has an LOV-enabled attribute. In the |
|
|
Generated for BLOB and CLOB attributes by default. This relationship indicates that the link is pointing to a resource that cannot be represented with the supported payload types. An image, that cannot be represented in JSON, is an example of this relationship. |
|
|
Generated for a resource that exists outside of the framework domain. |
15.3.5.2 href Attribute Value
The href attribute defines the URL to the linked resource or resource describe.
15.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.
15.4 Retrieving the ADF REST Resource
The ADF REST framework supports the following GET method use cases:
-
Fetching a resource collection.
-
Fetching a paged resource collection.
-
Filtering a resource payload using query parameters.
-
Fetching a resource item.
-
Fetching nested child resources.
-
Fetching a sorted resource collection.
15.4.1 Fetching a Resource Collection
ADF REST framework supports fetching a resource collection using a GET method.
The following sample fetches version v1 of the Departments resource collection and five items.
-
URL
http://server/sample/rest/v1/Departments -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 5, "hasMore" : true, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments", "name" : "Departments", "kind" : "collection" } ] }
15.4.2 Paging a Resource Collection
The ADF REST framework 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 framework 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 is to always include the limit query parameter to ensure only the desired number of resource items are returned and not more.
-
URL 1
http://server/demo/rest/v1/Departments?limit=2 -
URL 2
http://server/demo/rest/v1/Departments?offset=2&limit=2 -
URL 3
http://server/demo/rest/v1/Departments?offset=4&limit=2 -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : true, "limit" : 2, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments", "name" : "Departments", "kind" : "collection" } ] } -
Payload 2
{ "items" : [ { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : true, "limit" : 2, "offset" : 2, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments", "name" : "Departments", "kind" : "collection" } ] } -
Payload 3
{ "items" : [ { "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 1 "hasMore" : false, "limit" : 25 "offset" : 4, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments", "name" : "Departments", "kind" : "collection" } ] }
15.4.3 Filtering a Resource Collection with a Query Parameter
ADF REST framework supports fetching a resource collection using a GET method using query parameters. The resource collection may be queried using these expressions.
Supported operators:
-
Greater than:
> -
Less than:
< -
Greater than or equal to:
>= -
Less than or equal to:
<= -
And:
AND -
Or:
OR -
Equals:
= -
Like:
LIKE
Special Characters:
-
Define literals:
"and' -
Escape:
\ -
Wildcard:
*
The following sample fetches departments assigned a DepartmentId value less than 30.
-
URL
http://server/demo/rest/v1/Departments?q=DepartmentId<30 -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments", "name" : "Departments", "kind" : "collection" } ] }
15.4.4 Fetching a Resource Item
ADF REST framework supports fetching an item of the resource collection using a GET method.
The following sample fetches version v1 of all fields of an instance of the Departments resource collection.
-
URL
http://server/demo/rest/v1/Departments/50 -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.4.5 Fetching Nested Child Resources
The ADF REST framework supports retrieving nested resources using a GET method.
The following samples return version v1 of the Employees resource as a child of the Departments resource. The first request sample (URL1) 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 (URL2) shows the use of the query parameter expand to ensure that all nested Employees resource items will be returned with Department resource collection 50.
Note that the name used to identify the nested resource is determined at design time when the view accessor is created in the ADF Business Components project. The default name for the destination accessor in an DeptToEmpFkLink accessor is EmployeesView1. For this reason, it is a best practice for ADF REST resource developers to rename the destination accessor to something more suitable as a URL parameter. In this example, the default accessor name EmployeesView1 was changed to Employees in the view link overview editor to follow the naming convention for the parent resource name Departments.
-
URL 1
http://server/demo/rest/v1/Departments/50/child/Employees/120 -
URL 2
http://server/demo/rest/v1/Departments/50?expand=Employees -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/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/v1/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/50/child/Employees/120", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/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/v1/Departments/50/child/Employees/121", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/50/child/Employees/121", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" } ] }, { ... } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" } ] }
15.4.6 Sorting a Resource Collection
ADF REST framework 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 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 fetches the Employees collection sorted by the salary attribute. Since the sort order flag is not specified, the response is ascending order.
-
URL 1
http://server/demo/rest/v1/Departments?orderBy=DepartmentName -
URL 2
http://server/demo/rest/v1/Departments/50/child/Employees?orderBy=Salary -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 40, "DepartmentName" : "Human Resources", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/40", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/40/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 20, "DepartmentName" : "Marketing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/20", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/20/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 30, "DepartmentName" : "Purchasing", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/30", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/30/child/Employees", "name" : "Employees", "kind" : "collection" } ] }, { "DepartmentId" : 50, "DepartmentName" : "Shipping", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/50", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/50/child/Employees", "name" : "Employees", "kind" : "collection" } ] } ], "count" : 5, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/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/v1/Employees/132", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/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/v1/Employees/136", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Employees/136", "name" : "Employees", "kind" : "item" } ] } ], "count" : 2, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.5 Creating a Resource Item
The ADF REST framework supports the following creation use cases:
-
Creating a resource item in collection.
-
Creating a child resource item.
15.5.1 Creating a Resource Item in Collection
The ADF REST framework supports creating resource items using a POST method.
The following sample creates a new Departments resource collection with a single item.
-
URL
http://server/demo/rest/v1/Departments -
HTTP Method
POST
-
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DepartmentId" : 15, "DepartmentName" : "NewDept" }
-
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/v1/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.5.2 Creating Child Resource Item
The ADF REST framework 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.
-
URL 1
http://server/demo/rest/v1/Departments/15/child/Employees -
URL 2
http://server/demo/rest/v1/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 } ] }
-
HTTP Code
201 -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Location
http://server/demo/rest/v1/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/v1/Departments/15/child/Employees/999", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/15/child/Employees/999", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/v1/Departments/15/child/Employees/999/lov/JobsView1", "name" : "JobsView1", "kind" : "collection" } ] } -
Location
http://server/demo/rest/v1/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/v1/Departments/17/child/Employees/99999", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/17/child/Employees/99999", "name" : "Employees", "kind" : "item" }, { "rel" : "parent", "href" : "http://server/demo/rest/v1/Departments/17", "name" : "Departments", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/v1/Departments/17/child/Employees/99999/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } ], "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/17", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/17", "name" : "Departments", "kind" : "item" } ] }
15.6 Updating a Resource Item
The ADF REST framework supports the following update use cases:
-
Updating a resource item.
-
Replacing a resource item.
15.6.1 Updating a Resource Item
The ADF REST framework 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.
-
URL
http://server/demo/rest/v1/Departments/15 -
HTTP Method
PATCH
-
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DepartmentId" : 15, "DepartmentName" : "UpdatedDeptName" }
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DepartmentId" : 15, "DepartmentName" : "UpdatedDeptName", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.6.2 Replacing a Resource Item
The ADF REST framework supports replacing resource items using a PUT method. Replace will only succeed when the row already exists.
The following sample replaces Departments item 15, where the attribute DepartmentName is changed in the request payload. Note that attributes that are not specified in the request payload will be set to NULL.
-
URL
http://server/demo/rest/v1/Departments/15 -
HTTP Method
PUT
-
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DepartmentId" : 15, "DepartmentName" : "ReplacedDeptName" }
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DepartmentId" : 15, "DepartmentName" : "ReplacedDeptName", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.7 Deleting a Resource Item
The ADF REST framework 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.
-
URL 1
http://server/demo/rest/v1/Departments/17/child/Employees/99999 -
URL 2
http://server/demo/rest/v1/Departments/17 -
HTTP Method
DELETE
-
Content-Type
none
-
Payload
none
-
HTTP Code
204 -
Content-Type
none
-
Payload
none
15.8 Checking for Data Consistency
The ADF REST framework 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 framework 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/v1/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 Section 4.10.11, "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/v1/Departments/10",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C69737
47881D21D99C7619D03000149000473697A65787000000001770400000001737200186F721
636C652E6A626F2E646F6D61696E2E4E7564A362286F0200015B0004646174617400025B45
27870757200025B42ACF317F8060854E00200007870"
}
"links" : [ {
"rel" : "self",
"href" : "http://127.0.0.1:7101/RESTDemo2/rest/v1/Departments/10",
"name" : "Departments",
"kind" : "item",
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/v1/Departments/10",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "ACED0005737200136A6176612E7574696C2E149000473697A6578
70000000017704000000017372001B6F7261636C652E6A626F2E646F60000C78"
}
}, {
"rel" : "child",
"href" : "http://server/demo/rest/v1/Departments/10/child/Employees",
"name" : "Employees",
"kind" : "collection",
} ]
}, {
"DepartmentId" : 20,
"DepartmentName" : "Marketing",
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/v1/Departments/20",
"name" : "Departments",
"kind" : "item",
"properties" : {
"changeIndicator" : "ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619D03000149000473697A65787000000001770400000001737200186F7261636C652E6A626F2E646F6D61696E2E4E756D626572A5B1371914E0BFDA0200014900096D48617368436F6465787200116F7261636C652E73716C2E4E554D424552E90466EE632BE1D5020000787200106F7261636C652E73716C2E446174756D4078F514A362286F0200015B0004646174617400025B427870757200025B42ACF317F8060854E0020000787000000002C10A0000000078"
}
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/v1/Departments/20",
"name" : "Departments",
"kind" : "item"
}, {
"rel" : "child",
"href" : "http://server/demo/rest/v1/Departments/20/child/Employees",
"name" : "Employees",
"kind" : "collection"
} ]
}, {
...
} ]
} ],
"count" : 5,
"hasMore" : true,
"limit" : 25,
"offset" : 0,
"links" : [ {
"rel" : "self",
"href" : "http://server/demo/rest/v1/Departments",
"name" : "Departments",
"kind" : "collection"
} ]
}
15.8.1 Checking for Data Consistency When Updating ADF REST Resource Items
The ADF REST framework support checking for data consistency when using a PATCH method to update resource items backed by an ADF Business Components entity object with a change-indicator attribute enabled.
To check for data consistency using the ETag header and conditional header fields:
-
Obtain the ETag value from the header of a GET request for the resource item:
HTTP/1.1 200 OK Cache-Control: no-cache, no-store, must-revalidate Location: Content-Length: 861 Content-Type: application/json ETag: "responseETag123" Content-Encoding: Link: <http://server/demo/rest/v1/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/v1/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "responseETag123" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] } -
Make the PATCH request for the resource item and check for data consistency by supplying the following conditional header field:
-
If-Match: "<ETag value from resource item response>"to verify 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 (Request1), 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 (Request2), 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.
-
URL 1
http://server/demo/rest/v1/Departments/10 -
HTTP Method
PATCH
-
Precondition 1
If-Match: "responseETag123" -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload 1
{ "DepartmentName" : "FirstAttempt_NewDepartmentName" }
-
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/v1/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "responseETag567" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
-
URL 2
http://server/demo/rest/v1/Departments/10 -
HTTP Method
PATCH
-
Precondition 2
If-Match: "staleETag789" -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload 2
{ "DepartmentName" : "SecondAttempt_NewDepartmentName" }
-
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/v1/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "responseETag567" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.8.2 Checking for Data Consistency When Retrieving ADF REST Resource Items
The ADF REST framework support checking for data consistency when using a GET method to retrieve resource items backed by an ADF Business Components entity object with a change-indicator attribute enabled.
To check for data consistency using the ETag header and conditional header fields:
-
Obtain the ETag value from the header of a GET request for the resource item:
HTTP/1.1 200 OK Cache-Control: no-cache, no-store, must-revalidate Location: Content-Length: 861 Content-Type: application/json ETag: "responseETag123" Content-Encoding: Link: <http://server/demo/rest/v1/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/v1/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "ACED0005737200136A6176612E7574696C2E4" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] } -
Make the GET request for the resource item and check for data consistency by supplying the following conditional header field:
-
If-None-Match: "<ETag value from resource item response>"to verify 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 (Request1), 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 (Request2), 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.
-
URL 1
http://server/demo/rest/v1/Departments/10 -
HTTP Method
GET
-
Precondition 1
If-None-Match: "responseETag123" -
Content-Type
none
-
Payload
none
-
HTTP Code
304state not modified -
Content-Type
none
-
Payload 1
none
-
URL 2
http://server/demo/rest/v1/Departments/10 -
HTTP Method
GET
-
Precondition 2
If-None-Match: "unmatchedETagXYZ" -
Content-Type
none
-
Payload
none
-
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/v1/Departments/10", "name" : "Departments", "kind" : "item", "properties" : { "changeIndicator" : "responseETag123" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Departments/10", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v1/Departments/10/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.9 Versioning the Resource
In JDeveloper, ADF REST resource developers create version identifiers and associate these identifiers with the resources they create. The use of the version identifier allows the REST resource developer to manage updating an existing resource definition. When a resource needs to be updated with a change that is not backward compatible with the previous version, the resource developer may create a new version of the resource and assign it a unique version identifier.
The ADF REST framework 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. The ADF REST framework supports retrieving resources by their status field. Resources that have been tagged with the lifecycle status deprecated will no longer be accessible by the service client.
15.9.1 Retrieving All Available Versions
The ADF REST framework supports retrieving the version identifiers in the resource catalog using a GET method. The specific resource versions are those that have been associated at design time with the resources. Release version identifiers are defined in the Release Version page of the adf-config.xml overview editor.
The following sample fetches all resource version identifiers (v1, v2, and v3) defined in the resource catalog. Note that two links of type predecessor-version and successor-version specify the location of each version relative to their position in the list of versions.
-
URL
http://server/demo/rest -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.version+json -
Payload
{ "items" : [ { "version" : "v3", "isLatest" : true, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v3", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v3", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/v2", "name" : "predecessor-version", "kind" : "item" } ] }, { "version" : "v2", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v2", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2", "name" : "canonical", "kind" : "item" }, { "rel" : "predecessor-version", "href" : "http://server/demo/rest/v1", "name" : "predecessor-version", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/v3", "name" : "successor-version", "kind" : "item" } ] }, { "version" : "v1", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1", "name" : "self", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1", "name" : "canonical", "kind" : "item" }, { "rel" : "successor-version", "href" : "http://server/demo/rest/v2", "name" : "successor-version", "kind" : "item" } ] } ], "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/v3", "name" : "current", "kind" : "item" } ] }
15.9.2 Retrieving a Specific Version
The ADF REST framework 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 (request1) returns v1 and the second resource describe (request2) returns v2. The resource describe for v2 shows additional attributes HireDate and PhoneNumber have been defined on the resource.
-
URL 1
http://server/demo/rest/v1/Departments -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v1/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { ... } ] }, "item" : { "links" : [ { ... } ], }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v1/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } }
-
URL 2
http://server/demo/rest/v2/Departments -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v2/Employees", "name" : "self", "kind" : "collection" } ], "actions" : [ { ... } ] }, "item" : { "links" : [ { ... } ] }, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v2/Employees/describe", "name" : "self", "kind" : "describe" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2/Employees/describe", "name" : "canonical", "kind" : "describe" } ] } } }
15.10 Working with Attachments
The ADF REST framework supports content streaming for BLOB or CLOB attributes.
LOB attributes may be handled in the following ways.
-
Linked to as custom content that is not contained in the payload itself.
This is the default for BLOB and CLOB attributes and specified in the response payload using the
enclosurelink type to point to a resource that cannot be represented with the supported payload types (such asimage/png). -
Encoded into
Base64string format and contained in the request payload itself.
Currently, advanced features (like support for Chunked encoding) are not supported by the ADF REST framework. 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" : "replace",
"method" : "PUT",
"requestType" : [ "application/octet-stream" ]
}, {
"name" : "delete",
"method" : "DELETE"
}, {
"name" : "get",
"method" : "GET",
"responseType" : [ "application/octet-stream" ]
} ]
} ],
"item" : {
"links" : [ {
...
}, {
"rel" : "enclosure",
"href" : "http://server/demo/rest/v1/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.model.servlet.rest.binding.inputhandler.LinkInputHandler
15.10.1 Streaming Attachments Using a Resource Item Enclosure Link
The ADF REST framework 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, PUT (create or replace), 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 in Section 15.10.2, "Replacing LOB Content Using Base64."
To stream content from a link:
-
Retrieve the resource item and locate the
enclosurelink for the desired attribute. Theitemsection defines the available links for the attribute.Alternatively, you can execute the resource describe to identify the enclosure link generated for resource items. In general, the resource describe contains other useful information not returned in the GET response payload, including the expected response type (
image/png, for example) and supported actions for the attribute. -
Execute an HTTP operation (GET, PUT, 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/v1/Employees/101",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "canonical",
"href" : "http://server/demo/rest/v1/Employees/101",
"name" : "Employees",
"kind" : "item"
}, {
"rel" : "lov",
"href" : "http://server/demo/rest/v1/Employees/101/lov/JobsLOV",
"name" : "JobsLOV",
"kind" : "collection"
}, {
"rel" : "enclosure",
"href" : "http://server/demo/rest/v1/Employees/101/enclosure/Picture",
"name" : "Picture",
"kind" : "other"
} ]
}
For example, the following sample streams the PNG image associated with employee 101. In the create and update case, the image file could be used as the payload of an HTTP PUT request, where the URL points to the image link. For example, in curl format the following PUT operation updates the image for employee 101.
curl -X PUT -i -H "Accept: image/png" -H "Content-Type: image/png"
--data @C:\EmployeeImages\Emp101Image.png
http://server/demo/rest/v1/Employees/101/enclosure/Picture
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 appear in the resource item describe.
-
URL
http://server/demo/rest/v1/Employees/101/enclosure/Picture -
HTTP Method
GET
-
Content Type
none
-
Payload
none
-
HTTP Code
200 -
Content-Type
image/png -
Payload
content streamed
15.10.2 Replacing LOB Content Using Base64
The ADF REST framework 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.
-
URL
http://server/demo/rest/v1/Employees/101 -
HTTP Method
PATCH
-
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "Picture" : "/9j/4AAQSkZJRgABAAEAYABgAAD//..." }
-
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/v1/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" }, { "rel" : "self", "href" : "http://server/demo/rest/v1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v1/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "enclosure", "href" : "http://server/demo/rest/v1/Employees/101/enclosure/Picture", "name" : "Picture", "kind" : "other" } ] }
15.11 Working with LOV
The ADF REST framework supports retrieving the values from LOV-enabled attributes using a GET method.
To work with LOV-enabled attributes:
-
Execute the resource describe and locate the following details about the LOV:
Under the
lovdescription of an attribute, locate thechildRefproperty to identify the child resource collection that contains the LOV choices.The
lovdescription contains the attribute mapping from the resource item to the LOV child resource collection. The attribute mapping contains one or more source attributes from the child resource whose values will be copied to the resource item when an LOV value is selected. An LOV selection could derive more values in the resource item besides the attribute displaying the LOV. In such cases, the attribute mapping will identify it asderived = true. Finally, thelovdescription identifies which attributes from the child resource collection could be used for displaying to end users if the results are bound to a user interface. -
Then, look for the
linkselement and locate the link with areloflovand thehrefthat identifies the corresponding LOV child resource (as specified in thechildRefproperty). -
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 source attributes listed in the
lovdescriptions. A resource item update requires the source attribute values to apply the LOV selection.
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" : "JobTitle",
"target" : "JobId"
} ],
"displayAttributes" : [ "JobTitle" ]
}
...
"item" : {
"links" : [ {
"rel" : "lov",
"href" :
"http://server/demo/rest/v2/Employees/{id}/lov/JobsLOV",
"name" : "JobsLOV",
"kind" : "collection"
}, {
...
The following sample fetches the values for the LOV source attribute JobTitle from the JobsLOV collection. The query parameter onlyData ensures the representation is filtered to contain only data in the response payload, where President and Administration Assistant are examples of the values of the source attribute JobTitle.
-
URL
http://server/demo/rest/v2/Employees/101/lov/JobsLOV?onlyData=true&fields=JobTitle -
HTTP Method
GET
-
Content-Type
none
-
Payload
-
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/v2/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] }
15.12 Advanced Operations
The ADF REST framework supports the following advanced use cases:
-
Querying a resource with a partial get 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.
15.12.1 Querying with a Partial Get to Restrict Attributes
The ADF REST framework supports retrieving a subset of fields from resource collections using a GET method.
The following sample fetches the values for an instance of the Departments collection. The query parameter fields ensures the response payload contains only the specified attributes: FirstName, LastName, and Email.
-
URL
http://server/demo/rest/v2/Employees/101?fields=FirstName,LastName,Email -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "FirstName" : "Neena", "LastName" : "Smith", "Email" : "NSMITH", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v2/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/v2/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] }
15.12.2 Filtering a Resource Collection with a Row Finder
ADF REST framework 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 framework supports passing parameters into these filters and supports using the seeded filters to reduce the collection.
Filtering with a row finder is performed using the finder query string parameter values to specify one or more row finder parameter values. The finder query string parameter format is:
<finder>=<rowfinderName>;<attr1>=<value1>,<attr2>=<value2>,...
Example: finder=DeptByName;Dname=ACCOUNTING
The resource collection describe explains the shape of a row finder. To work with the row finder:
-
Execute the resource describe and locate the
findersattribute in the collection element. Thenameattribute identifies the row finder. Also locate the name of the row finder parameter underattributes. -
Execute a GET with the query parameter
finderand identify the row finder using the finder name.
For example, the Departments resources describe returns the following:
"collection" : {
"rangeSize" : 25,
"finders" : [ {
"name" : "EmpByEmailRF",
"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 EmpByEmailRF where the Email attribute value NSMITH is passed.
-
URL
http://server/demo/rest/v2/Employees?finder=EmpByNameRF;Email=NSMITH -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v2/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/v2/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } ], "count" : 1, "hasMore" : false, "limit" : 25, "offset" : 0, "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v2/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.12.3 Returning Only Resource Data in a Payload
The ADF REST framework 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.
-
URL
http://server/demo/rest/v2/Employees?onlyData=true -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v2/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.12.4 Returning the Estimated Count of Resource Items
The ADF REST framework 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.
-
URL
http://server/demo/rest/v2/Employees?totalResults=true&limit=2 -
HTTP Method
GET
-
Content-Type
none
-
Payload
none
-
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/v2/Employees/NSMITH", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2/Employees/NSMITH", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/v2/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/v2/Employees/LDEHAAN", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2/Employees/LDEHAAN", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/v2/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/v2/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.12.5 Executing a Custom Action
The ADF REST framework 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.
-
URL
http://server/demo/rest/v2/Employees/101 -
HTTP Method
POST
-
Content-Type
application/vnd.oracle.adf.action+json -
Payload
{ "name": "multiplySalary", "parameters": [ { "multiplicand": "2" } ] }
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.actionresult+json -
Payload
{ "result" : 4000.0 }
15.12.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 framework allows 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.
-
URL
http://server/demo/rest/v2/Departments/15 -
HTTP Method
POST
-
X-HTTP-Method-Override
PATCH
-
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DepartmentName": "UpdatedDept", }
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.resourceitem+json -
Payload
{ "DepartmentId" : 15, "DepartmentName" : "UpdatedDept", "links" : [ { "rel" : "self", "href" : "http://server/demo/rest/v2/Departments/15", "name" : "Departments", "kind" : "item" } }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2/Departments/15", "name" : "Departments", "kind" : "item" }, { "rel" : "child", "href" : "http://server/demo/rest/v2/Departments/15/child/Employees", "name" : "Employees", "kind" : "collection" } ] }
15.12.7 Making Batch Requests
The ADF REST framework 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.
-
URL
http://server/demo/rest -
HTTP Method
POST
-
Content-Type
application/vnd.oracle.adf.batch+json -
Payload
{ "parts": [ { "id": "part1", "path": "/v2/Employees/101", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part2", "path": "/v2/Employees/102", "operation": "update", "payload": { "Salary": 10000 } }, { "id": "part3", "path": "/v2/Employees/103", "operation": "update", "payload": { "Salary": 10000 } } ] }
-
HTTP Code
200 -
Content-Type
application/vnd.oracle.adf.batch+json -
Payload
{"parts": { { "id" : "part1", "path" : "/v2/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/v2/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2/Employees/101", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/v2/Employees/101/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } }, { "id" : "part2", "path" : "/v2/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/v2/Employees/102", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2/Employees/102", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/v2/Employees/102/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } }, { "id" : "part3", "path" : "/v2/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/v2/Employees/103", "name" : "Employees", "kind" : "item" }, { "rel" : "canonical", "href" : "http://server/demo/rest/v2/Employees/103", "name" : "Employees", "kind" : "item" }, { "rel" : "lov", "href" : "http://server/demo/rest/v2/Employees/103/lov/JobsLOV", "name" : "JobsLOV", "kind" : "collection" } ] } } ] }
15.13 ADF REST Framework Reference
The ADF REST framework supports HTTP methods, HTTP headers, request URL parameters, media types, and other concepts to enable making REST API calls on resources.
15.13.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 15-3 describes the content-encoding tokens supported by ADF REST framework.
Table 15-3 Supported Content-Encoding Tokens
| Content-Encoding | Description |
|---|---|
|
|
Does not compress the payload. The behavior is the same as when the encoding is omitted. |
|
|
Compresses the payload using the format produced by the file compression program |
|
|
Compresses the payload with a combination of the |
15.13.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 15-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 15-4 Media Types Supported by the ADF REST Framework
| Media Type | Invocation Context | Description |
|---|---|---|
|
|
GET method POST method |
Represents the format for all resource collections returned by the ADF REST framework. All attributes are automatically generated by the framework. Only the content of the For an example, see Section 15.3.2, "Describing a Resource Collection." |
|
|
GET method POST method PUT method DELETE method PATCH method |
Represents the format for all resource items returned by the ADF REST framework. Only the attribute For an example, see Section 15.3.3, "Describing a Resource Item." |
|
|
POST method |
Describes custom action execution and their parameters. Exposed custom actions are backed by methods of a view object interface or view row interface. For an example, see Section 15.12.5, "Executing a Custom Action." |
|
|
POST method |
Describes the result of an action execution. For an example, see Section 15.12.5, "Executing a Custom Action." |
|
|
GET method |
Describes the resource and its elements. For an example, see Section 15.3.1, "Describing All Available Resources." |
|
|
POST method |
Describes a set of operations to be performed, where the operation consists of a set of parts and each part represents a request. The batch request is executed in one single transaction. For an example, see Section 15.12.7, "Making Batch Requests." |
|
|
POST method |
Describes the result of a request to get all versions of a resource. For an example, see Section 15.9.1, "Retrieving All Available Versions." |
15.13.3 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 15-5 HTTP Codes Supported by ADF REST Framework
| HTTP Code | Description |
|---|---|
|
|
Request successfully executed and the response has content. |
|
|
Resource successfully created. The response contains the created resource. |
|
|
Request successfully executed and the response doesn't have content. |
|
|
According to the provided ETag, the resource was not modified. |
|
|
The request could not be understood by the server due to malformed syntax. |
|
|
The server is refusing to service the request because the resource of the request is secured and authentication has not yet been provided. |
|
|
The requested resource was not found. |
|
|
The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. |
|
|
The resource state in the server side doesn't match the provided ETag. |
|
|
The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. |
|
|
The server encountered an unexpected condition which prevented it from fulfilling the request. |
15.13.4 ADF REST HTTP Headers Support
The ADF REST framework supports the HTTP headers listed in the following table.
Table 15-6 HTTP Headers Supported by ADF REST Framework
| HTTP Header Name | Description |
|---|---|
|
|
Use to specify the content-type of the request/response payload. The ADF REST framework is able to interpret (request/response) the media types as described in Section 15.13.2, "ADF REST Media Types." |
|
|
Use to specify the content-encoding of the request/response payload. The ADF REST framework is able to parse a compressed request that uses the encodings as described in Section 15.13.1, "ADF REST Payload Compression Support." |
|
|
Use to specify the expected content-type of the response payload. The ADF REST framework is able to interpret (request/response) the media types as described in Section 15.13.2, "ADF REST Media Types." |
|
|
Use to specify the list of acceptable encoded responses. The ADF REST framework is able to generate a response using the encodings described in Section 15.13.1, "ADF REST Payload Compression Support." |
|
|
Use to identify the URI of a newly created resource. The ADF REST framework includes the |
|
|
Use to compare the state of the resource in a request with the state of resource on the server. The ADF REST framework supports the |
|
|
Use to determine whether the state of the resource in a request is current with the resource on the server. This header is supported in order to execute conditional requests. For more information, see Section 15.8, "Checking for Data Consistency." |
|
|
Use to determine whether the state of the resource in a request does not match the current state on the server. This header is supported in order to execute conditional requests. For more information, see Section 15.8, "Checking for Data Consistency." |
|
|
Use to execute an action that is otherwise not supported by the server. This is a custom header (not defined by the HTTP specification) that contains the name of an HTTP method as its value. This value (if valid) will be used to define the HTTP method that will be used. This header will only be considered in a POST request. For more information, see Section 15.12.6, "Overriding the HTTP Method and Performing an Update." |
|
|
Use to avoid intermediate proxies to cache/store framework payloads, this header is configured for every HTTP response. Valid values are: |
15.13.5 ADF REST HTTP Method and Payload Support
The ADF REST framework supports operations on the following HTTP methods.
-
GET -
POST -
PUT -
PATCH -
DELETE
15.13.5.1 GET Method Operations
The ADF REST framework supports the following operations using a GET method with the URI as shown.
-
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}]]
-
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 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}]
-
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. Note that query string parameters can only be used on resource media types. They cannot, for example, be used when describing the resource.
Table 15-7 Supported Resource Media Type GET Method Query String Parameters
| GET URI Parameter | Resource Type (Item | Collection) | Value | Description |
|---|---|---|---|
|
|
resource collections only |
One or more expressions, separated by semi-colons. Format: Example: |
The resource collection will be queried using the provided expressions. Supported operators:
Special Characters:
For an example, see Section 15.4.3, "Filtering a Resource Collection with a Query Parameter." |
|
|
resource collections only |
An expression containing information about the finder and its parameters. Format: Example: |
The resource collection will be queried using the provided finder/parameter. The list of available finders is provided in the describe. Finders with parameters whose type does not belong to For an example, see Section 15.12.2, "Filtering a Resource Collection with a Row Finder." |
|
|
both |
A comma separate list of resource collection attributes. Format: Example: |
This parameter filters the resource collection attributes. Only the specified attributes are returned. For an example, see Section 15.12.1, "Querying with a Partial Get to Restrict Attributes." |
|
|
both |
boolean Default: |
The representation will be filtered in order to contain only data (no For an example, see Section 15.12.3, "Returning Only Resource Data in a Payload." |
|
|
resource collections only |
boolean Default: |
The resource collection representation will include the estimated row count when For an example, see Section 15.12.4, "Returning the Estimated Count of Resource Items." |
|
|
both |
A comma separate list of accessors. Format: Example: |
When this parameter is provided, the specified first-level children are included in the resource payload (instead of the link). Note that currently only first level children may be expanded. For an example, see Section 15.4.5, "Fetching Nested Child Resources." |
|
|
resource collections only |
integer Default: Iterator binding |
This parameter restricts the number of resources returned inside the resource collection. If the limit exceeds the resource total results, then the framework will return the available resources. For an example, see Section 15.4.2, "Paging a Resource Collection." |
|
|
resource collections only |
integer Default: 0 (the first position) |
Used to define the starting position of the resource collection. If offset exceeds the resource count, then no resources are returned. For an example, see Section 15.4.2, "Paging a Resource Collection." |
|
|
both |
A set of dependency attributes. Format: Example: |
The dependencies are attributes that are set before and rolled back after generating the response. Generally, they are used to preview the effects of an attribute change as it applies to cascading LOV-enabled attributes. The dependencies attributes are always set in the resource item in question. When a child resource collection is requested and the |
|
|
both |
A comma separated list of order-by attributes with a sort flag to specify ascending or descending order. Format: Example: Default: ORDERBY attributes defined on the view object query backing the resource will be applied. |
Orders a resource collection based on its attributes. If the For an example, see Section 15.4.6, "Sorting a Resource Collection." |
-
Request
-
None
-
-
Response
-
application/vnd.oracle.adf.resourcecollection+json: When retrieving a resource collection. -
application/vnd.oracle.adf.resourceitem+json: When retrieving a resource item. -
application/vnd.oracle.adf.description+json: When describing a resource.
-
application/vnd.oracle.adf.version+json: When retrieving all available resource versions.
-
15.13.5.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}
-
none
-
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.
-
15.13.5.3 PUT Method Operations
The ADF REST framework supports the following operations using a PUT method with the URI as shown.
-
Replacing a resource item.
http://server/demo/rest/{version}/{resourceItemPath}
-
none
-
Request
-
application/vnd.oracle.adf.resourceitem+json: The resource item to be replaced.
-
-
Response
-
application/vnd.oracle.adf.resourceitem+json: The replaced resource item.
-
15.13.5.4 PATCH Method Operations
The ADF REST framework supports the following operations using a PATCH method with the URI as shown.
-
Updating a resource item.
http://server/demo/rest/{version}/{resourceItemPath}
-
none
-
Request
-
application/vnd.oracle.adf.resourceitem+json: The resource item to be updated.
-
-
Response
-
application/vnd.oracle.adf.resourceitem+json: The updated resource item.
-
15.13.5.5 DELETE Method
The ADF REST framework supports the following operations using a DELETE method with the URI as shown.
-
Deleting a resource item.
http://server/demo/rest/{version}/{resourceItemPath}
-
none
-
Request
-
none
-
-
Response
-
none
-