1. Oracle Global Human Resources Cloud REST APIREST API for Oracle Fusion Cloud HCM
  2. Learn More
  3. Set the REST Framework Version

Set the REST Framework Version

Oracle Fusion Cloud HCM REST APIs utilize our own end-to-end ADF REST API framework, simplifying the development experience. This framework supports creating and interacting with resources and REST services based on ADF Business Components. Client application developers can then use REST APIs to easily interact with public business objects. The different versions of the REST framework provide alternative ways of controlling REST API behavior.

Choose a REST Framework Version

For your application development, you can choose any one version among the eight REST framework versions (1 to 8). The version you choose for your client depends on your business needs.

Discovering your Default Framework Version

Oracle Fusion Cloud HCM REST APIs use framework version 1 by default. If it's appropriate for your business needs, then you're all set. If not, you can specify a different framework version in your client. Oracle recommends using the latest framework version to take advantage of the latest features. You can find the framework version information for an API in the defaultFrameworkVersion and allowedFrameworkVersions properties, in the response body of a GET request for the <context root> of the resource endpoint. For example: 

{
    "items" : [
        {
            "version" : "11.13.18.05",
            "isLatest" : true,
            "adf:extension" : {
                    "defaultFrameworkVersion" : "3",
                    "allowedFrameworkVersions" : [ "1", "2", "3", "4" ]            
            },
		}
	]
}

Note:

The changes introduced in each framework version are backward incompatible. Therefore, assess your business requirements and use the framework version that supports them.

To set the REST framework version for a client request:

  1. Choose one of the eight supported framework versions:
    Framework Description
    Version 1 The base framework version that's used to process client requests. Note that the query-by-example resource query syntax supported in version 1 is not compatible with later versions of the ADF REST framework.
    Version 2 Supports expanded query expression syntax for client requests. Version 2 introduces a backward-incompatible change for client requests that use version 1, because version 2 interprets the q query parameter differently.
    Version 3 Supports retrieving nested child resources for client requests as a collection resource, instead of an array of items, as in versions 1 and 2. Use the GET method with expand and fields query parameters to return a nested child resource with the hasMore attribute, and determine whether you can return more resource items in subsequent requests. Version 3 introduces a backward-incompatible change for client requests that use version 1 or 2, because of the difference in the payload structure.
    Version 4 Prior to version 4, the response payload only contains the error message as a string if a REST request fails. In version 4 and above, the error response payload contains richer information such as application-specific error code, error path that pinpoints where the error occurs, and details if an error is caused by other errors.
    Version 5 This version introduces two changes:
    • For custom methods returning non-string values, the response payload displays the value in the actual data type instead of displaying it as a string.
    • If a field is a dependent List of Value (LOV) field, then you may see that its LOV resource URL changes from a sub-resource to a root resource. LOV provides the list of valid values for a field. For example, the workers resource has a LegislationCode field, and its valid values come from a separate resource hcmCountriesLov.

      A dependent LOV provides valid values based on another field's value. For example, valid values of ReasonCode depends on the value of ActionCode.

      Prior to version 5, all dependent LOV resources are sub-resources, such as /emps/{empsUniqID}/lov/CitizenshipLegislationCodeLOV. In version 5, some dependent LOV resources become root resources such as /hcmCountriesLov. But client can still filter the dependent LOV resource based on its dependent field value, using a finder query parameter.

    Version 6 A new field @context is introduced with all item context information placed within it, in the response payload. This new @context field is a sibling of any regular field. It's of JSON object type and includes key, headers, links, and warnings if there are any.

    Note:

    Links are available even in prior versions, but in version 6, they are moved into the @context section.
    Version 7 Hides the row-level LOVs. Only the root-level LOV resource links are displayed in the resource metadata and resource data.

    A row-level LOV resource is a sub-resource with its URL containing lov, such as /emps/{empsUniqID}/lov/CitizenshipLegislationCodeLOV. In this example, the emps resource has a CitizenshipLegislationCode field. A valid CitizenshipLegislationCode value comes from another resource. This row-level CitizenshipLegislationCodeLOV resource is always a sub-resource of an existing emps resource. Therefore, a row-level LOV isn't useful when choosing a value, while creating a new employee. Instead, client should use a root-level LOV resource so that both create and update operations are covered.

    Version 8 This version introduces the following changes:
    • Support for storing and retrieving data of type ClobDomain as a plain string instead of base64 encoded value.
    • For requests sent to multi-select Fixed Choice List (FCL) fields, the values returned in the response are presented in an array instead of comma-separated list of values.
    • If an attribute is used as an identifier attribute in the resource URL, and the attribute value contains special characters, then the attribute value is encoded to make the resource URL constructed properly.
  2. Use the REST-Framework-Version custom HTTP header in the client request to specify the framework version.

When a default framework version is not defined and no version header is passed, then the base version (version 1) of the ADF REST framework is assumed. To learn more, see:

Examples

Let's look at some examples of HTTP requests and payload structures of nested child resources, depending on the framework version that's used to process the request.

Example: REST Framework Version 1 or Version 2

In this example, you can retrieve the grades resource, the GradeName and GradeCode attributes, and the specified items of the child resource, steps, as an array of items and not as a collection resource as in version 3.

cURL Command

curl --user <username:password> -H 'REST-Framework-Version:2' https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/grades?fields=GradeName,GradeCode;steps:GradeStepName&onlyData=true

Example Response

{
  "items": [
     {
          "GradeName": "VEN.1.East",
          "GradeCode": "GRDCD_1838",
          "steps": [
              {
                  "GradeStepName": "Step 1"
              },
              {
                  "GradeStepName": "Step 3"
              },
              {
                  "GradeStepName": "Step 2"
              },
              {
                  "GradeStepName": "Step 4"
              },
              {
                  "GradeStepName": "Step 5"
              }
          ]
      },
      {
          "GradeName": "VEN.2.East",
          "GradeCode": "GRDCD_1839",
          "steps": [
              {
                  "GradeStepName": "Step 1"
              },
              {
                  "GradeStepName": "Step 5"
              },
              {
                  "GradeStepName": "Step 2"
              },
              {
                  "GradeStepName": "Step 3"
              },
              {
                  "GradeStepName": "Step 4"
              }
          ]
      },

...
}

Example: REST Framework Version 3

In this example, you can retrieve the grades resource, the GradeName and GradeCode attributes, and the specified items of the child resource, steps, as a collection resource, and then set the hasMore attribute to false, indicating that there are no more items to fetch.

cURL Command

curl --user <username:password> -H 'REST-Framework-Version:3' https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/grades?fields=GradeName,GradeCode;steps:GradeStepName&onlyData=true

Example Response

{
  "items": [
      {
          "GradeName": "VEN.1.East",
          "GradeCode": "GRDCD_1838",
          "steps": {
              "items": [
                  {
                      "GradeStepName": "Step 1"
                  },
                  {
                      "GradeStepName": "Step 3"
                  },
                  {
                      "GradeStepName": "Step 2"
                  },
                  {
                      "GradeStepName": "Step 4"
                  },
                  {
                      "GradeStepName": "Step 5"
                  }
              ],
              "count": 5,
              "hasMore": false,
              "limit": 25,
              "offset": 0,
              "links": [
                  {
                      "rel": "self",
                      "href": "https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/grades/00020000000EACED00057708000000000000072E0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800000165D03A340078/child/steps",
                      "name": "steps",
                      "kind": "collection"
                  }
              ]
          }
      },
      {
          "GradeName": "VEN.2.East",
          "GradeCode": "GRDCD_1839",
          "steps": {
              "items": [
                  {
                      "GradeStepName": "Step 1"
                  },
                  {
                      "GradeStepName": "Step 5"
                  },
                  {
                      "GradeStepName": "Step 2"
                  },
                  {
                      "GradeStepName": "Step 3"
                  },
                  {
                      "GradeStepName": "Step 4"
                  }
              ],
              "count": 5,
              "hasMore": false,
              "limit": 25,
              "offset": 0,
              "links": [
                  {
                      "rel": "self",
                      "href": "https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/grades/00020000000EACED00057708000000000000072F0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800000165D03A340078/child/steps",
                      "name": "steps",
                      "kind": "collection"
                  }
              ]
          }
      },
...
}

Example: REST Framework Version 4

In this example to update a worker, the TerminationDate field causes a validation error. The response payload includes the HTTP status code and formats the details of the exception in an array structure.

cURL Command

curl --user <username:password> -X POST -H 'REST-Framework-Version:4' -H "Accept: application/vnd.oracle.adf.resourceitem+json,application/vnd.oracle.adf.error+json" https://servername.fa.us2.oraclecloud.com/hcmRestApi/resources/11.13.18.05/emps/00020000000EACED00057708000000000000017F0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800000165D03A340078

Example Request

{ 
  "MiddleName": "John",
  "TerminationDate": "2018-11-23"
}

Example Response

Content-Type : application/vnd.oracle.adf.error+json
REST-Framework-Version : 4
HTTP code: 400

{
  "title": "Bad Request",
  "status": "400",
  "o:errorDetails": [
      {
          "detail": "TerminationDate: Attribute TerminationDate in view object EmployeeVO cannot be set.",
          "o:errorCode": "27008",
          "o:errorPath": "/TerminationDate"
      }
  ]
}

No matter which framework you use, each REST framework supports HTTP methods, HTTP headers, request URL parameters, media types, and other concepts to allow you to execute REST API calls on resources.