Introduction to ADP API Open Data Protocol (OData)

About OData

OData is a standardized protocol built over existing Hypertext Transfer Protocol (HTTP) and Representational State Transfer (REST) protocols supporting CRUD (Create, Read, Update, Delete) operations for creating and consuming data APIs.
For more information, see: https://www.odata.org/getting-started/understand-odata-in-6-steps
For URL conventions, see: https://www.odata.org/documentation/odata-version-3-0/url-conventions

Common ADP OData Options

ADP APIs could support the following options defined in Open Data Protocol (OData):

• $select
• $filter
• $top
• $skip

These options allow a client device to control the representation it gets back from the server. Multiple query parameters may be used together by separating each option with the & character.

OData Parameter Types

The $select Parameter

The $select option selects a subset of properties to include in the response.
The following are examples using $select:

The $filter Parameter

The $filter option filters a collection of resources addressed by a request URL. The expression specified with $filter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response.
The following are examples using $filter:

The $top Parameter

The $top option requests the number of items in the queried collection to be included in the result.
The following request returns the first two workers of the workers collection:
GET https://api.adp.com/hr/v2/workers?$top=2

The $skip Parameter

The $skip option specifies the number of items in the queried collection to be skipped and not included in the result.
GET https://api.adp.com/hr/v2/workers?$skip=18

Pagination Using $top and $skip for Large Collections

The following request returns 20 workers, starting with the 51st worker of the workers collection while using the HR V2 Workers API and pagination using $top and $skip for large collections:
GET https://api.adp.com/hr/v2/workers?$top=20&$skip=50

Checking Whether a GET Call Supports $select or $filter

OData parameters can only be used with the GET calls. You need to call the meta version of the API. This can be done by appending /meta to the end of the resource.

Sample Response Snippet

The following is a sample response snippet from hr/v2/workers. The field "queryOptionCode": "$select" shows $select can be used as an OData parameter for the API and the following objects:

• email
• fax
• landline phones
• mobile phones

{
"meta": {
"queryCriteria": [
{
"itemID": "q1",
"queryOptionCode": "$select",
"queryOptionTypeCode": "OData",
"resourcePaths": [
"workers/associateOID",
"workers/businessCommunication",
"workers/businessCommunication/emails",
"workers/businessCommunication/faxes",
"workers/businessCommunication/landlines",
"workers/businessCommunication/mobiles",
"workers/businessCommunication/pagers",
"workers/customFieldGroup",
"workers/customFieldGroup/amountFields",
"workers/customFieldGroup/codeFields"
]
}
]
}
}

In the same way you can find out about the $filter parameter, If the ''/meta" response results in tags such as "queryOptionCode": "$filter", it implies the API supports the $filter parameter. 

In the following sample response snippet from hr/v2/workers the $filter parameter can be used as:

/hr/v2/workers/workAssignments/reportsTo/positionID%20eq%20%2794N293601%27

In the following snippet, 94N293601 is the value on which we are applying the filter:

{

"itemID": "q2",
"queryOptionCode": "$filter",
"queryOptionTypeCode": "OData",
"resourcePaths": [
"workers/workAssignments/reportsTo/positionID"
],
"queryValueCodeList": {

"listItems": [
{
"codeValue": "94N293601",
"shortName": "iattam1Manager, Test"
},
{
"codeValue": "94N000061",
"shortName": "Asciber, Ene"
},
{
"codeValue": "938009669",
"shortName": "BERROA, TERE J."
}
]
},
"logicalOperators": [
{


"logicalOperatorCode": "eq"
},
{
"logicalOperatorCode": "and"
}
]
}

Samples

Examples of $select and $filter Parameters

The difference between the $select and $filter parameters is you cannot use eq for the $select parameter.

Example 1: Using the $select Parameter

If you're using the $select parameter, then the request will look like the following:
hr/v2/workers?$filter=workers/workerID/idValue
The response contains idValue(s) for all the workers.

Example 2: Using the $filter Parameter

If you're using the $filter parameter, then the request will look like the following:
hr/v2/workers?$filter=workers/workerID/idValue eq '1A9HUHNNN'
When you are requesting a specific value by using the eq field name, you must use the $filter parameter. In the previous example, the response contains worker details with the idValue equal to 1A9HUHNNN.
The $filter parameter supports field values in single quotes only.