Working with REST API Framework Versions

About REST API Framework Versions

You may utilize a new feature or enhancement that is introduced in a version of the Oracle Business Object REST API framework if your application opts into the framework version within the visual development tool. A framework version refers to a specific version of the REST API framework that calls to REST APIs will use. Depending on the version, functionality for accessing business objects will vary.

It is important that you know the framework version enabled in your web application since you may need to pass a different payload format to utilize a new feature or enhancement. The framework version used to make calls is under your control so that you may opt into the functionality when you are ready.

These are the way the tooling allows you to specify the framework version to make calls:

Specify the default framework version to be used.
Specify the framework version using a custom request header when making the call.

You may pass the custom header REST-Framework-Version on the REST API request to specify the framework version to use to execute the request. The REST API framework version passed in the version header overrides the default framework declaration defined by the web application developer.

When your REST API call passes no version header, the calls use the default that you defined in the application. When you did not define the default framework version and do not pass a version header, then the version of the REST API framework is determined by the default setting enabled by the tooling.

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

You may want to find out the default framework version for a particular release. To support this use case, REST APIs will return the default framework version in the resource version describe, as the following sample shows. Note that you may override the default framework version with another framework version identifier by specifying the value in the REST-Framework-Version header. The allowedFrameworkVersions property lists the values of the available framework versions.

{
    "items" : [
        {
            "version" : "18.2",
            "isLatest" : true,
            "adf:extension" : {
                    "defaultFrameworkVersion" : "2",
                    "allowedFrameworkVersions" : [ "1","2","3","4","5","6","7" ]
            },
            "links" : [
             ...

For details about the REST API framework functionality supported in each framework version, see Understanding REST API Framework Version Support.

Understanding REST API Framework Version Support

You can specify a Oracle Business Object REST API framework version for your web application to opt into new functionality offered by a later version of the REST API framework. Currently, Oracle offers the following framework versions.

Note:

Each REST API framework version after version 1 introduces functionality that the previous framework versions does not support. Thus, when you choose to opt into a later framework version, the REST API may introduce backward incompatible changes on the web application consuming the REST API. This topic explains the changes for each framework version.

Framework Version 1

Note that the query-by-example resource query syntax supported in the base framework version (version 1) is not compatible with later versions of the REST API framework. Beginning with version 2 of the REST API framework, a more advanced query syntax is offered instead.

Framework Version 2

The purpose of this new version is to introduce an expanded query expression syntax for making REST API calls. Version 2 of the REST API framework will interpret the q query parameter value differently than the way framework version 1 does, and therefore introduces a backward incompatible change to web applications that rely on framework version 1. Only when framework version 2 (or later) is specified for the request will the REST API support the use of the expanded expression syntax to process the request.

In version 1, filtering resource collections using the q query parameter is limited to a query-by-example syntax, as follows.

GET /rest/19.0/Departments?q=Dname SA*;Loc BOSTON

Whereas, starting in version 2, the new advanced query syntax supports filtering resource collections using rowmatch query expressions, as follows.

GET /rest/19.1/Departments?q=Dname like 'SA*' or Loc = 'BOSTON'

For an explanation of the enhanced query syntax offered by rowmatch expressions, see Understanding Framework Support for Query Syntax.

Framework Version 3

The purpose of this version is to add support for retrieving nested child resources with payload attributes that may be used by the web application to determine whether more resource items would be returned in a subsequent REST API request. To support this functionality, the payload structure in framework version 3 now represents nested child resource as a resource collection, instead of an array of items, as was true in version 1 and 2. Therefore, version 3 introduces a backward incompatible change to web applications that rely on framework version 1 or version 2. If you decide to opt into version 3, you will expose functionality that allows GET operations to use the ?expand and ?fields query parameter to return a nested child resource as a resource collection with the hasMore attribute. In affect, this change supports pagination of nested child resource that would otherwise require more than one request to fetch.

When you want to add support for framework version 3 to your application, the same guidelines described for framework version 2 (see above section) apply for preserving the existing level of functionality in the web application.

For an example of the new payload structure for nested child resources introduced in version 3, see Fetching a Child Business Object and Fetching a Business Object with a Subset of Items. For details about paginating a resource collection using the hasMore attribute, see Paging a Business Object.

Framework Version 4

Version 4 is the default version that the REST APIs will use to process requests for web applications when no other version is specified.

In addition to HTTP status codes and error messages, it is possible to obtain exception details in the response when your request is enabled to use REST API framework version 4 and the request is made for either application/vnd.oracle.adf.error+json or application/json media types. With framework version 4, the response will be in the form an exception detail payload which provides the following benefits to the web application:

If multiple errors occur in a single request, the details of each error are presented in a hierarchical structure.
An application-specific error code may be present that identifies the exception corresponding to each error.
An error path may be present that identifies the location of each error in the request payload structure.

Note:

The exception detail may or may not present certain details, such as the application-specific error code and the request payload’s error path.

For example, compare the error response for a POST submitted with a payload that contains the following incorrectly formatted date field when framework version 3 (or earlier) is enable and when framework version 4 (or later) is enabled.

{    "EmpNum" : 5027,
     "EmpName" : "John",
     "EmpHireDate" : "not a date"
}

Standard Error Response

Without framework version 4, no response payload is generated and instead only a single error message that does not reference the request payload will be returned in the response.

"An instance of type oracle.jbo.domain.Date cannot be created from string not a date. The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm."

Exception Payload Error Response

With framework version 4 (or later) enabled, the following exception detail payload is generated for the response. The payload includes the usual HTTP status code and formats the details of one or more exceptions in an array structure.

{    "title" : "Bad Request",
    "status" : "400",
    "o:errorDetails" : [ {
     "detail" : "An instance of type oracle.jbo.domain.Date cannot be created from string not a date. 
               The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm.",
       "o:errorCode" : "26099",
       "o:errorPath" : "/EmpHireDate"
    } ]
 }

Framework Version 5

Framework version 5 is not supported for users of visual development tools provided by Oracle Cloud services.

Framework Version 6

The purpose of this framework version is to easily differentiate between the resource fields and item information like links and headers. A new element @context is introduced in this version and all the information for an item is moved under @context. The changeIndicator value is moved to ETag, which is under headers. A new context information key is included under @context that contains the unique identifier of the specific resource item as a string.

The new payload for a resource item in a response payload and collection response payload will be similar to the one below:

{
     "field1": "value1",
     "field2": "value2",
      ...
     "@context" : {
          "key" : "AB8765BCD",
          "headers" : {
              "ETag" : "ACED00057372001..."
          },
          "links": [
           {
             "rel": "self",
             "href": "https://<baseurl>/accounts/CDRM_53640",
             "name": "accounts",
             "kind": "item"
           },
           { // other links }}
         ]
      }
}

Framework Version 7

The enhancements provided by framework version 7 are not supported for users of visual development tools provided by Oracle Cloud services.

Framework Version 8

Framework version 8 enhances support for ClobDomain fields, multi-select LOV fields, and primary key values in queries.

ClobDomain fields used in REST GET/POST/PATCH requests now make use of string values without the need for base64 encoding/decoding. Earlier framework versions rely on base64 encoding of ClobDomain fields and therefore require base64 decoding to return a text value.
Multi-select LOV fields are now represented in the describe as array type, and request and response will have array values for multi-select LOV fields. Earlier framework versions return multi-select LOV fields as one string with comma-separated values. Starting with framework version 8, when creating or updating (POST/PATCH) multi-select LOV fields, the payload expects an array of values.
Several changes were made to support special use cases when working with primary key values. Specifically, framework version 8 and above supports encoding key values in REST queries to enable the use of special characters and composite values in the URL path.

1. In the case of a simple key, where the primary key has only one string/number attribute, framework version 8 and above allows special characters in key values and these values should be encoded in the URL path.

Where OrderName is a key attribute with a value that contains a slash:

"Sales/Marketing"

With framework version 8 or above, you can encode the value so the URL path looks like:

/orders/Sales%252FMarketing

2. In the case of a composite primary key, framework version 8 and above allows concatenation of the key values in a comma separated list and these values should be encoded in the URL path.

Where OrderItem is a key attribute with the composite key value:

"Sales/Marketing", LineItemId: 1, Status: "New"

With framework version 8 or above, you can encode the value so the URL path looks like:

/orders/Sales%2FMarketing/child/items/Sales%252FMarketing%2C1%2CNew

Or, where the composite contains a null value:

"Sales/Marketing", LineItemId: 2, Status: null"

The URL path looks like this:

/orders/Sales%2FMarketing/child/items/Sales%252FMarketing%2C2%2C

Framework Version 9

Framework version 9 enhances support for high-precision numeric fields, accessors in a URL, and queries using a LIKE operator:

High-precision view attributes rely on deserialization by JavaScript clients to represent values. With deserialization, some loss of precision is possible for values greater than 15 digits. To avoid a potential loss of precision, starting with framework version 9, high-precision numeric values are converted to JSON string type. The REST client needs to convert the value from string type to a big integer or big decimal before any numeric computation is performed. If numeric computation is not required, then treat these values as strings.
Nested child resources may be accessed using accessor dot notation in the ?field and ?expand query parameters of the REST URL. Starting with framework version 9, the REST client will return 400 Bad Request when an accessor is referenced in the URL and that accessor has not been previously exposed by the REST resource developer as a view link accessor.
Starting with framework version 9, ?q queries that involve a LIKE operator, may use a \ (backslash) character as an escape character to support queries for these wildcard characters % (percent), * (asterisk), _ (underscore), and ? (question mark) and also for the \ (backslash) character. For example:

?q=Dname like '%\%%' - query for Dname containing %

?q=Dname like '%\*%' - query for Dname containing *

?q=Dname like '%\_%' - query for Dname containing _

?q=Dname like '%\?%' - query for Dname containing ?

?q=Dname like '%\\%' - query for Dname containing \

Using the Request Header to Specify the REST API Framework Version

REST APIs support executing individual requests on the service endpoint using a custom header to affect the processing of the payload with the functionality specific to a particular Oracle Business Object REST API framework version. The framework version specified by the custom header overrides the default framework version declaration that may exist in the client application.

Note:

A framework version refers to a specific version of the Oracle Business Object REST API framework. For details about the REST API framework functionality supported in each framework version, see Understanding REST API Framework Version Support.

To process a request using a specific REST API framework version, the request must pass the custom header REST-Framework-Version with the framework version number specified. For example, the following header specifies framework version 2 will be used to process the request that passes this version header.

     REST-Framework-Version: 2

If the custom header is omitted on the request, then REST APIs will use the application’s default framework version, as defined in the web application. When the application does not define a default framework version and the request omits the version header, then the base version (version 1) of the REST API framework is assumed.