Introduction to ADP API Open Data Protocol (OData)

Summary

ADP application programming interfaces (APIs) support the following optional parameters defined in Open Data Protocol (OData):

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

These parameters 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.

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/.

OData Parameter Types

About the $select Parameter

The $select parameter selects a subset of properties to include in the response.

The following table shows examples using the $select parameter.

About the $filter Parameter

The $filter parameter 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 table shows examples using the $filter parameter.

About the $top Parameter

The $top parameter 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

About the $skip Parameter

The $skip parameter 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 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 eq '94N293601'

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"
}
]
}

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.