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.
|
To get … |
Use the following query … |
|---|---|
|
Only the legal name of each worker: |
GET https://api.adp.com/hr/v2/workers?$select=workers/person/legalName |
|
Both the legal name and Associate Object Identifier (AOID) of each worker: |
GET https://api.adp.com hr/v2/workers? $select=workers/associateOID,workers/person/legalName |
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.
|
To get … |
Use the following query … |
|---|---|
|
Only workers reporting to Jane Doe: |
GET https://api.adp.com/hr/v2/workers?$filter=workers/workAssignments/reportsTo/positionID eq '93V000061' |
|
To get workers reporting to Jane Doe and workers whose status is Active: |
GET https://api.adp.com/hr/v2/workers?$filter=workers/workAssignments/assignmentStatus/statusCode/codeValue eq 'A' and workers/workAssignments/reportsTo/positionID eq '94N000061' |
Supported $filter resource paths will vary by ADP product.
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
While using Pagination, when you reach the end of all the records, a 204 response code with No Content will be returned.
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:
- 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.
