Collection Filtering

Filtering allows the client to request a subset of resources from a collection that satisfy specific Boolean expressions. The filter expression is applied to individual resources in the collection.

For example, a transaction contains several filterable properties:

  • the date the transaction was processed
  • the type and subtype of the transaction
  • an amount object, with value and the currency for that transfer amount

Simple filtering

The simplest form of filtering is exact matching. These can be done with simple query parameters on the GET operation to the collection, such as:

GET /transactions/pastTransactions?amount=210.50
GET /transactions/pastTransactions?date=2017-10-02&type=debit

As a convenience, the vertical bar character | may be used to separate between one choice or another:

GET /transactions/scheduledTransactions?state=inactive|pending

This means select items where state is either inactive or pending.

Range Filters

Range filters are flexible bounds for values. Filters can be set to a closed range of values (such as the start date and end date of a month) or they can be open ended (such as any amount over $100.00).

In general, the formatting for a range filter follows the below patterns with a lowerBound and a upperBound. Brackets [] are used for values that include the nearest bound. Parenthesis () are used for values that exclude the nearest bound. Brackets and parenthesis can be mixed together, as long as there is always an opening and closing character.

  • lowerBound matches the the value exactly
  • [lowerBound,upperBound] matches items where lowerBound <= value <= upperBound
  • [lowerBound,] matches items where value >= lowerBound
  • [,upperBound] matches items where value <= upperBound
  • (lowerBound,upperBound) matches items where lowerBound < value < upperBound
  • (lowerBound,) matches items where value > lowerBound
  • (,upperBound) matches items where value < upperBound
  • [lowerBound,upperBound) matches items where lowerBound <= value < upperBound
  • (lowerBound,upperBound] matches items where lowerBound < value <= upperBound
  • [lowerBound,) means lowerBound <= value (the equivalent of [lowerBound,])
  • (,upperBound] means upperBound <= value (the equivalent of [,upperBound])
  • [,upperBound) means upperBound < value (the equivalent of (,upperBound))

Specific documentation for the range type, such as amountRange and dateRange, is available in the API documentation.

Combining filters

When two or more of these filters are combined, they are joined with an implicit and operator.

For example, the query below matches only transactions that were posted on 2017-10-02 and transactions whose type is debit.

GET /transactions/pastTransactions?date=2017-10-02&type=debit

On this page