Filtering

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

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

Multiple conditions are joined using AND. 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

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 ?id=!1,2,3,4 or ?status!=assigned,accepted

less than
Less than given value (not for enums, strings and booleans)

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

less than or equal to
Less than or equal to given value (not for enums, strings and booleans)

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

greater than
Greater than given value (not for enums, strings and booleans)

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

greater than or equal to
Greater than or equal to given value (not for enums, strings and booleans)

?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(not for enums, strings and booleans)

?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(not for enums, strings and booleans)

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

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:

Most available fields for each model can be used in filters, but at least one field should be indexed. If none of the filter conditions reference an indexed field, the following error message will be shown:

States

Most models have predefined states similar to the state buttons found in the ITRP UI. They can be applied using the ?state= parameter, or by appending /<state> to the URI path.

$ curl https://api.itrp.com/v1/requests?state=open

$ curl https://api.itrp.com/v1/requests/open

It is possible to combine states and filters.

It is also possible to use states 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 change, or the internal notes of a request.

$ curl https://api.itrp.com/v1/changes/:id/requests/open

$ curl https://api.itrp.com/v1/requests/:id/notes/internal