Filtering and sorting
Salsa allows you to easily filter requests and sort response data.
How to use filters
Filters allow you to specify the data you want to retrieve from Salsa's APIs. Regardless of which API you call, filters operate uniformly, and are applied with the filter
parameter. For each filter, you must supply a fieldName
and the value you wish to filter for.
Filter for a single value
When filtering string or enum fields with a single value, use the following request format:
GET /api/endpoint?filter[stringField]=value
This filter retrieves data where stringField
matches the specified value
.
Filter for multiple values
When filtering string fields for multiple values, values must be provided as an array. For example:
GET /api/endpoint?filter[stringField]=[value1, value2]
This filter retrieves data where stringField
matches any of the specified values within the array (value1
or value2
).
Filter for dates
For date fields, specific operators must be applied with the filter value:
onOrBefore(date)
: Retrieves objects with a date on or before the specified date.onOrAfter(date)
: Retrieves objects with a date on or after the specified date.onOrBetween(startDate, endDate)
: Retrieves objects where the date is within the range provided.
Example usage:
GET /api/endpoint?filter[dateField]=onOrBefore(2023-01-01)
Replace dateField
with the appropriate date field in your API, and ensure to follow the correct syntax for the date operators.
Date interval fields
For fields containing date intervals (objects with startDate
and endDate
), use the contains(date)
operator. For example:
GET /api/endpoint?filter[intervalField]=contains(2023-01-01)
Replace intervalField
with the appropriate interval field in your API and ensure to follow the correct syntax for the date operators.
Apply multiple filters
Filters can be combined to further narrow down query results by using multiple filter parameters. For example:
GET /api/endpoint?filter[field1]=value1&filter[field2]=value2
Refer to the REST API documentation for a comprehensive list of available fields and their specific filtering capabilities.
How to sort responses
Sorting for list responses is achieved by specifying the field name of the value to be used to determine the order, as well as the direction of the sort (ascending or descending).
Field names are specified using the same syntax as filters, see details on the specification below.
To indicate the direction of the sort, you can prefix the field name with -
in to indicate descending, otherwise the sort order will be ascending. For example, to sort paystubs by pay date in descending order, your request would look like this:
curl --request GET \
--url 'https://api.sandbox.salsa.dev/api/rest/v1/employers/${employerId}/workers/${workerId}/worker-payment-records?page=0&size=500&sort=-payDate' \
--header 'accept: application/json' \
--header 'authorization: Bearer ADD_TOKEN'
Sorting with multiple criteria is also supported, and can be achieved by appending additional field names to the request. If no sorting criteria are specified, then the sort order of a list response is not guaranteed.
Field name specification
- Field names within filters correspond to the field names in the REST response object.
- Filters are case-sensitive; ensure accurate spelling and casing when applying filters.
- For nested fields, the field name should be specified using dot notation. e.g. to refer to the
payDate
field that is a property of thepayPeriod
that is part of the resource, you would usepayPeriod.payDate
.
Updated 7 months ago