HCM REST Training

Contents
Working with collection resources ............................................................................................................... 3
Reading a collection .................................................................................................................................. 3
Read a collection ................................................................................................................................... 3
Read a collection at a point in time ...................................................................................................... 3
Limit attributes returned ...................................................................................................................... 3
Expand child resources ......................................................................................................................... 3
Get specific attributes of child resource ............................................................................................... 4
Exclude all links ..................................................................................................................................... 4
Querying a collection ................................................................................................................................ 4
Querying numeric attributes................................................................................................................. 5
Querying string attributes ..................................................................................................................... 5
Querying date attributes....................................................................................................................... 5
Querying child resource attributes...................................................................................................... 5
Querying by combining criteria............................................................................................................. 5
Querying using finders .......................................................................................................................... 6
Navigating through a collection ................................................................................................................ 6
Fetching the total number of items ...................................................................................................... 6
Controlling the page size....................................................................................................................... 7
Paging through the collection ............................................................................................................... 7
Sorting a collection ................................................................................................................................... 8
Sort on a single field.............................................................................................................................. 8
Sort on a single field descending order.............................................................................................. 8
Sort on multiple fields ........................................................................................................................... 9
Modifying a collection............................................................................................................................... 9
Add an item to a collection ................................................................................................................... 9
Delete an item from a collection ........................................................................................................ 10
Working with a singular REST resource ...................................................................................................... 11
Read a resource ...................................................................................................................................... 11
Read a resource at a point in time .......................................................................................................... 11
Limit attributes returned ........................................................................................................................ 11
Exclude all links ....................................................................................................................................... 12
 HCM REST Training

Read a child resource .............................................................................................................................. 12

Expand a child resource .......................................................................................................................... 12
Get specific attributes of a child resource .............................................................................................. 12
Checking for modifications ..................................................................................................................... 12
 HCM REST Training

Working with collection resources

Reading a collection

Read a collection

To read a collection, simply access collection resource URL

Reading a top level resource
GET /resources/latest/emps

Reading a child resource

GET /resources/latest/emps/00020000000EACED00057708/child/assignments

Read a collection at a point in time

To read a collection at a given point in time, access the collection resource URL with effectiveDate
parameter
GET /resources/latest/emps?effectiveDate=2016-02-02

Limit attributes returned

To decrease the size of the retrieved payload, specify which attributes should be returned by
using fields parameter:
GET
/resources/latest/emps?fields=DisplayName,WorkPhoneNumber,DateOfBirth

Expand child resources

To reduce number of API calls, fetch child resources inline for collection items.
Use expand parameter where child resources can be specified.
GET
/resources/latest/emps?expand=roles,assignments,assignments.assignment
DFF
 HCM REST Training

Keyword all can be used to expand all the child resources, including LOVs. Note that it is possible to
retrieve nested child resources (across multiple levels).
GET /resources/latest/emps?expand=all

Get specific attributes of child resource

The expand parameter cannot be combined with fields parameter. However, fields parameter can be
used to retrieve child resource attributes. This effectively allows to expand child resources.
GET
/resources/latest/emps?DisplayName,FirstName,LastName;assignments:JobI
d,DepartmentId;roles:RoleName;assignments.assignmentDFF:AssignmentId

Exclude all links

The onlyData parameter can be used to exclude all the links in the response payload and thereby
reduce the size of the retrieved response.

GET
resources/latest/emps?fields=DisplayName,FirstName,LastName,MaritalStatus,Hir
eDate,TerminationDate&onlyData=true

Querying a collection

The q parameter can be used to filter a collection by comparing attribute values. The following
operators are used to compare an attribute

Operator Attribute Comparison

= equal to a value
> Greater than a value
< Less than a value
>= Greater than or equal to a value
<= Less than or equal to a value
<> Not equal to a value
In In a list of values
is null Value is null
Is not null Value is not null
between Between two values
LIKE Compare string values
AND Used to AND comparisons
OR Used to OR comparisons
UPPER Used to transform string attribute values to uppercase
 HCM REST Training

Querying numeric attributes

GET /resources/latest/emps?q=PersonId=1000
GET /resources/latest/emps?q=PersonId>1000
GET /resources/latest/emps?q=PersonId between 1000 and 1100
GET /resources/latest/emps?q=PersonId in (1053, 1200, 1300)
GET /resources/latest/emps?q=CitizenshipId is not null

Querying string attributes

GET /resources/latest/emps?q= FirstName like 'Ki%'

GET /resources/latest/emps?q= FirstName not like 'Ki%
GET /resources/latest/emps?q= FirstName is null
GET /resources/latest/emps?q= UPPER(FirstName) = 'KIM
GET /resources/latest/emps?q= UPPER(FirstName) like 'KI%

Querying date attributes

GET /resources/latest/emps?q= DateOfBirth > '1960-01-01'

GET /resources/latest/emps?q= DateOfBirth between '1960-01-01' and
'1960-01-10'

Querying child resource attributes

You can include attributes of child resources in the query. In the examples below, assignments and roles
are child resources of emps
GET /resources/latest/emps?q= assignments.PositionId in (407, 67, 23)
GET /resources/latest/emps?q= roles.RoleName like 'Sales%'

Querying by combining criteria

 HCM REST Training

You can combine query criteria using AND and OR

GET /resources/latest/emps?q= (Gender = 'M' AND CitizenshipStatus =
'A') OR (Ethnicity = '1')
GET /resources/latest/emps?q= (DateOfBirth > '1960-01-01' ) AND
(assignments.JobId in (13,18))

Querying using finders

Finders are pre-defined queries associated with a resource.

This finder runs a pre-defined query that retrieves all employees that belong to a business unit
GET /resources/latest/emps?finder=
findByAssignmentAttr;BusinessUnitName=AK Procurement1

Finders can be combined with query parameters

GET /resources/latest/emps? finder=
findByAssignmentAttr;BusinessUnitName=AK Procurement1&q= Gender = 'F'

Navigating through a collection

Fetching the total number of items

Set totalResults parameter to true (default is false ) to retrieve the total number of items in a collection,
If a query is provided, totalResults will indicate number of items matching the query criteria.
GET /resources/latest/emps?q=FirstName=Kim&totalResults=true

The response will be as follows

{
"items" : [ {
"FirstName" : "Kim",
"LastName" : "Brock",
...
],
"totalResults" : 9,
"count" : 6,
"hasMore" : true,
"limit" : 6,
"offset" : 0,
"links" : [ {
"rel" : "self",
"href" :
"http://slcai713.us.oracle.com:10619/hcmCoreApi/resources/11.12.1.0/emps",
 HCM REST Training

"name" : "emps",
"kind" : "collection"
} ]
}

Controlling the page size

Each call to a collection resource will return a fragment of the collection - a single "page". The size of the
page is 25 items by default. This size can be specified by using the limit parameter:
GET /resources/latest/emps?q=FirstName=Kim&limit=4

Paging through the collection

Page through the collection, by using the offset parameter. The value of offset is 0 by default, which will
fetch items from the beginning of the collection. To fetch the next page of the collection, increase the
offset by the limit value.
The hasMore attribute in the response indicates if there is more data to fetch. so the process should be
repeated until hasMore is set to false.
The count attribute in the response indicates the number of items fetched in the response
In the example below we have 9 items in the collection and we will be fetching 4 items in a single call.

GET /resources/latest/emps?q=FirstName='Kim'&limit=4
200 OK
{
"items" : [ {
"FirstName" : "Kim",
..],
"count" : 4,
"hasMore" : true,
"limit" : 4,
"offset" : 0,
"links" : [ {
"rel" : "self",
"href" :
"http://slcai713.us.oracle.com:10619/hcmCoreApi/resources/11.12.1.0/emps",
"name" : "emps",
"kind" : "collection"
} ]
}

GET /resources/latest/emps?q=FirstName='Kim'&limit=4&offset=4

200 OK
{
"items" : [ {
 HCM REST Training

"FirstName" : "Kim",
.. } ],
"count" : 4,
"hasMore" : true,
"limit" : 4,
"offset" : 4,
"links" : [ {
"rel" : "self",
"href" :
"http://slcai713.us.oracle.com:10619/hcmCoreApi/resources/11.12.1.0/emps",
"name" : "emps",
"kind" : "collection"
} ]
}

GET /resources/latest/emps?q=FirstName='Kim'&limit=8&offset=4

200 OK

{
"items" : [ {
"FirstName" : "Kim",
..
} ],
"count" : 1,
"hasMore" : false,
"limit" : 4,
"offset" : 8,
"links" : [ {
"rel" : "self",
"href" :
"http://slcai713.us.oracle.com:10619/hcmCoreApi/resources/11.12.1.0/emps",
"name" : "emps",
"kind" : "collection"
} ]
}

Sorting a collection

To sort a collection, use orderBy parameter. Specifying the attributes to sort on and direction to sort by
(ascending, descending).

Sort on a single field

GET /resources/latest/emps?q=FirstName like K% & orderBy=FirstName

Sort on a single field descending order

 HCM REST Training

GET /resources/latest/emps?q=FirstName like K% &

orderBy=FirstName:desc

Sort on multiple fields

GET /resources/latest/emps?q=FirstName like K% & orderBy=

FirstName,LastName:desc

Modifying a collection

Add an item to a collection

To add an item to a collection, make a POST request to the collection resource URL.

The Content-Type header must be set to application/vnd.oracle.adf.resourceitem+json . This is

required for POST and PATCH requests.

Example below adds a base64-encoded photo to employee photos collection.

POST
/resources/latest/emps/00020000000EACED000577080000000000000018/child/photo
Content-Type: application/vnd.oracle.adf.resourceitem+json

{
"ImageName" : "ProfilePhoto",
"PrimaryFlag" : "Y",

"Image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAq
ERilSpVRZ//Z"
}

The response will return the representation of the newly created photo resource
201 CREATED

{
"ImageName": "ProfilePhoto",
"PrimaryFlag": "Y",
''
"links": [
{
"rel": "self",
...
},
{
"rel": "canonical",
...
},
{
 HCM REST Training

"rel": "parent",
...
},
{
"rel": "enclosure",
"href": "...",
"name": "Image",
"kind": "other"
}
]
}

To prevent the newly-created resource representation from being retuned in the response, use
the Accept request header, specifying a content type with 0 qualifier:
POST
/resources/latest/emps/00020000000EACED000577080000000000000018/child/photo
Accept: application/json;q=0
Content-Type: application/vnd.oracle.adf.resourceitem+json

{
"ImageName" : "ProfilePhoto",
"PrimaryFlag" : "Y",

"Image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAq
ERilSpVRZ//Z"
}

204 No Content

Delete an item from a collection

To delete an item from a collection, make a DELETE request to the individual resource URL.

For example, to delete a photo, you first need to obtain the self link to the photo - either by calling child
resource URL directly or expanding it inline.

Get the link to the photo

GET
/resources/latest/emps/00020000000EACED000577080000000000000018/child/photo

{
"items": [
{
"ImageName": "ProfilePhoto",
"PrimaryFlag": "Y",
"ImageId": 300100074650412,
"PersonId": 24,
"ObjectVersionNumber": 1,
"links": [
{
 HCM REST Training

"rel": "self",
"href": "http.//...",
..
},
..
]
}
],
..
]
}

Delete the photo using the self link

DELETE
/resources/latest/emps/00020000000EACED000577080000000000000018/child/photo/3
00100074650412

204 No Content

Working with a singular REST resource

Read a resource

To read a resource simply access it's individual resource URL

GET /resources/latest/emps/00020000000EACED000577080000000000000018

Read a resource at a point in time

To read a date effective resource at a given point in time, use the effectiveDate parameter
GET /resources/latest/emps/00070000004AACED00057372000D6A61?
effectiveDate=1995-03-03

Limit attributes returned

Similarly to collection resource requests, you can limit the attributes returned using the
fields parameter

GET /resources/latest/emps/00070000004AACED00057372000D6A61?fields=
DisplayName,FirstName,LastName,Gender
 HCM REST Training

Exclude all links

Similarly to collection resource you can limit the links returned, by using onlyData parameter:
GET
/resources/latest/emps/00070000004AACED00057372000D6A61?onlyData=true

Read a child resource

Access the child resource directly using its URL

GET
/resources/latest/emps/00070000004AACED00057372000D6A61/child/assignme
nts

Expand a child resource

Expand child resources to get them along with the parent resource, using the expand parameter:

GET
/resources/latest/emps/00070000004AACED00057372000D6A61?expand=assignm
ents

Get specific attributes of a child resource

Use the fields parameter, to include attributes of one or more child resources
GET /resources/latest/emps/00070000004AACED00057372000D6A61?fields=
DisplayName,FirstName,LastName;assignments:JobId,DepartmentId;roles:Ro
leName;assignments.assignmentDFF:AssignmentId

Checking for modifications

To save on processing time and payload size, you can cache the resource on the client and conditionally
fetch the resource only if modifications occurred. This can be achieved using the ETag infrastructure.

First an ETag value has to be obtained. For a GET operation on a singular resource, it is returned as
the ETag response header:
 HCM REST Training

GET
/resources/latest/emps/00020000000EACED00057708?fields=DisplayName&onl
yData=true

200 OK
Etag: "ACED0005737200136A6176612E7574696CA6176612E6C616E672E4"

{
"DisplayName": "Kim Brock"
}

Save the returned ETag value and pass it subsequent GET requests through the If-None-Match request
header. This indicates that we only want the payload to be returned if the resource was modified (by
other party).
GET
/resources/latest/emps/00020000000EACED00057708?fields=DisplayName&onl
yData=true

If-None-
Match: "ACED0005737200136A6176612E7574696CA6176612E6C616E672E4"

If no modifications are made to the resource, server will just acknowledge (and not send a resource
payload)
304 Not modified

On the other hand, if the resource was modified, server will respond with the current representation
and the new ETag value. Save this ETag value for subsequent calls.
200 OK
Etag: "FCED00057372000000014770400000014737A76612E6C616E672E4"

{
"DisplayName": "Kim Brock"
}

Update a resource

To update a resource, make a PATCH request to the resource URL. Set the Content-Type header to
application/vnd.oracle.adf.resourceitem+json and include the payload with the required changes.
PATCH /resources/latest/emps/00020000000EACED000577080000000000000018
Content-Type: application/vnd.oracle.adf.resourceitem+json

{
"MaritalStatus": "M"
}
 HCM REST Training

The response will contain current representation and ETag value in the response header.
200 OK
Etag:
"ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619
D03000149000473697A6578700000001477040000"

(...)

"MaritalStatus": "M",

(...)

"links": [
{
"rel": "self",
"href":
"https://slcai713.us.oracle.com:10620/hcmCoreApi/resources/11.12.1.0/e
mps/00020000000EACED0005770800000000000000180000004AACED00057372000D6A
6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E757469
6C2E44617465686A81014B597419030000787077080000015C62742D8078",
"name": "emps",
"kind": "item",
"properties": {
"changeIndicator":
"ACED0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619
D03000149000473697A6578700000001477040000"
}
},

(...)

]
}

If you do not want the response to contain the rsource payload, use
the Accept request header, specifying a content type with 0 qualifier:
PATCH /resources/latest/emps/00020000000EACED000577080000000000000018
Accept: application/json;q=0
Content-Type: application/vnd.oracle.adf.resourceitem+json

{
"MaritalStatus": "M"
}
 HCM REST Training

The server response will not contain the resource payload. It will only return the ETag

204 No Content
Etag:
"ACEF0005737200136A6176612E7574696C2E41727261794C6973747881D21D99C7619
D03000149000473697A6578700000001477040000"

Delete a resource

To delete a resource, make a DELETE request to the resource URL:

DELETE
/resources/11.12.1.0/emps/00020000000EACED000577080000000000000018/chi
ld/photo/300100074710030

204 No Content