Filtering

When requesting a collection of resources the resulting list can be reduced by passing one or more filter conditions:

$ curl https://api.r-service.tech/v1/requests?status=assigned\
       &next_target_at=>2011-10-01T00:00:00Z

Multiple conditions are joined using AND .

Allowed filters

Not all fields can be filtered. The fields that support filtering are listed for each individual API.

If you need more extensive filtering capabilities, such as the capability to filter on custom fields, please use the R-Service GraphQL API .

Allowed operators

The following operators can be used in filter conditions:

equality

Same as given value

?id=43523 or ?name=foo

negation

Different from given value

?status=!assigned or ?team_id=!4

Literal values starting with !

In some cases, a field value may begin with an exclamation mark (!) as part of the actual value rather than as an operator.

For example:

primary_email = !bobrova.sofya@domain.com

name = !Important Project

If such a value is used in a filter without escaping, the leading ! will be interpreted as a negation operator.

Example:

?primary_email=!bobrova.sofya@domain.com

This request will be interpreted as “not equal” and will return all records except the specified value.

To match a literal value that starts with !, escape it using a backslash ():

?primary_email=\!bobrova.sofya@domain.com

Escaping ensures that ! is treated as part of the value and not as an operator.

empty

Has no value (null)

?team_id= or ?remarks=

present

Contains a value (not null)

?team_id=! or ?remarks=!

in

Equal to one of the given values ( integers and enums only )

?id=1,2,3,4 or ?ids=1,2,3,4 or ?status=assigned,accepted

not in

Not equal to one of the given values ( integers and enums only )

?id=!1,2,3,4 or ?ids=!1,2,3,4 or ?status!=assigned,accepted

less than

Less than given value ( numeric and date/time types only )

?created_at=<2016-01-15T23:00:00Z or ?purchase_value=<90.00

less than or equal to

Less than or equal to given value ( numeric and date/time types only )

?warranty_expiry_date=<=2016-01-15 or ?nr_of_licenses=<=30

greater than

Greater than given value ( numeric and date/time types only )

?completed_at=>2016-01-15T23:00:00Z or ?nr_of_processors=>2

greater than or equal to

Greater than or equal to given value ( numeric and date/time types only )

?updated_at=>=2016-01-15T23:00:00Z or ?salvage_value=>=100.00

greater than and less than

Greater than given value and less than the other given value ( numeric and date/time types only )

?date=>2015-12-31<2016-02-01 or ?assignment_count=>3<10

greater than or equal to and less than or equal to

Greater than or equal to given value and less than or equal to the other given value ( numeric and date / time types only )

?date=>=2016-01-01<=2016-01-31 or ?assignment_count=>=4<=9

For date time target fields like response_target_at, resolution_target_at and next_target_at, the following special values are also accepted: best_effort , clock_stopped , no_target .

For string and text fields like name and subject , filtering is case sensitive, unless otherwise specified.

See the Data Types section for more information on the formatting of input values.

Filter Exceptions

Not all combinations of filters are allowed and not all operators can be used on all fields. In case an invalid filter condition is applied a Bad Request response will be returned.

Status: 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "message": "..."
}

Some example messages are:

• “Field ‘disabled’ does not support the ‘=>’ operator”
• “Cannot apply the ‘=’ operator to a set of values for field ‘subject’”
• “Cannot filter on a set of values for field ‘disabled’”
• “Unknown fields: disabled, strange”
• “Filtering not allowed on fields: times_applied”

Predefined Filters

Most models have predefined filters, similar to the state buttons and views found in the R-Service UI. They can be applied by appending /<predefined_filter> to the URI path:

$ curl https://api.r-service.tech/v1/requests/open

Alternatively, the ?state= parameter can be used to apply a predefined filter:

$ curl https://api.r-service.tech/v1/requests?state=open

$ curl https://api.r-service.tech/v1/requests/requested_by_or_for_me?state=open

It is possible to combine predefined filters and filter conditions.

It is also possible to use predefined filters to look up only certain relations of a specific record. This make it possible to, for example, look up the open requests that are linked to a workflow, or the internal notes of a request.

$ curl https://api.r-service.tech/v1/workflows/:id/requests/open

$ curl https://api.r-service.tech/v1/requests/:id/notes/internal