Hi community,

I noticed that the blog “Oracle HCM Cloud REST API how-to miniseries I” is getting popular and today I am going to continue on the topic related to REST APIs in the Oracle HCM Cloud.

I would like to share one important point related to the REST API calls. It’s a REST API framework version.

You may utilize new features or enhancements by specifying a framework version. Depending on the version, functionality for accessing business objects will be different.

Oracle HCM Cloud supports 7 (?) framework versions:

• Framework Version 1: Default framework version used in the REST API calls
• Framework Version 2: Supports extended query expression syntax. Version 2 introduces a backward-incompatible change for client requests that use version 1 because version 2 interprets the q query parameter differently.
• Framework Version 3: Supports retrieving nested child resources. The JSON structure in version 3 represents nested child resources as a collection resource, instead of an array of items as in previous versions. Use the GET method with expand and fields query parameters to return a nested child resource with the hasMore attribute and determine whether more resource items would be returned in subsequent requests.
• Framework Version 4: Enable this version to display REST API error responses in JSON format.
• Framework Version 5: 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.
• Framework Version 6: A new field @context is introduced with all item context information placed within it, in the response payload.
• Framework Version 7: Hides the row-level LOVs. Only the root-level LOV resource links are displayed in the resource metadata and resource data.

A full list of changes introduced by each version you can review here: https://docs.oracle.com/en/cloud/saas/human-resources/21c/farws/Setting_the_REST_Framework_Version.html

Keep in mind that every next version introduces a backward-incompatible change for client requests that use the previous versions because of the difference in the payload structure.

To set a specific version use the REST-Framework-Version custom header in a client request to specify the framework version for the request. If this custom header is not set, the default framework version 1 is used to process the request.

I prefer using Advanced REST Client by MuleSoft 🙂

Let’s see some examples:

• The first one demonstrates using a @context field introduced in the version 6.

• The second one is about getting errors in the JSON format. Let’s try to update a worker DoB and CountryOfBirth

Pick a worker /hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber=100055

Copy a {workersUniqID} to use it in the PATCH

Now switching to the Version 4 and submit it again…

As a conclusion, it makes sense to review output generated by different framework versions to find the most suitable for the certain cases. And then use it while building a REST API client code.

That’s it. I hope you find it helpful.

SY,
Volodymyr