Apperio Filter API

The filter endpoints provide resource discovery in Apperio. This hastwo basic mechanisms. Firstly there are the resource discovery endpoints.These are: * `/api/v1/filter/engagements/` * `/api/v1/filter/invoices/` * `/api/v1/filter/matter-tags/`These endpoints return lists of resource references with decorating metadatathat can be filtered, ordered and paginated.Secondly resources may be tagged. The tag management endpoints allow you tocreate different groupings of mattersFor those familiar with writing SQL queries, the resource discovery endpointscan be thought of in a similar way. The `SELECT` section or projection clausedetermines which fields are returned. The `WHERE` clause or filter section determineswhich records are returned and `ORDER BY` section determines the order that they arereturned in. Ordering and pagination is covered in the section above. Below, we willtake each of the other sections in turn to show how these are handled on these endpoints. **Data Projection**The filter API is designed to provide broad information about resources for easy resourcediscovery. The client can choose which denormalised fields can appear in the projectionclause using the `fields` query parameter. Only the fields listed in this query parameter,together with any mandatory fields, will be included in the response.The field names are URL encoded comma (%2C) separated.For example if I wish to bring back the fields `one`, `two` and `three` I would query theendpoint with:```...?fields=one%2Ctwo%2Cthree```And the response will bring back only those fields and any mandatory fields (such as theidentifier for the resource). For example the response may be:```json{ "results": [ { "one": 5000.0, "two": 5, "three": false }, { "one": 86645.23, "two": 59541, "three": false } ], "pagination": { "next": null, "previous": null, "nextPage": null, "previousPage": null }}```The full list of available fields can be seen in the response body for that endpoint.**Resource Permissions**The set of resources that can be discovered in the API is limited to those thatthe user generating the token has access to. This can then be filtered furtherusing explicit filters; resources that the user is not authorized to see will notbe returned.**Filtering the data**On the resource discovery endpoints the returning data can be filteredby each of the fields on the resource. Each field has been associated withthe type of filter that will make it easier to discover resources. The filtertypes are explained below. *Range filters*Range filters allow a slice of the data to be selected. They can be used toselect all data less than equal to a value; all data above or equal to a valueor can be combined to return a slice of the data. For example if I have thefield `foo` and wish to return all data between 10000 and 12000 GBP I would addthe filters:```?foo__gte=10000&foo__lte=12000```When the field is a monetary field it is assumed that these values will be inyour organisation's base currency and any transactions in another currency willbe subject to a exchange conversion on the rate held for the date of thattransaction.**Text filters**Text filters will return all entries that start with the selected value. Forexample if I wanted to bring back all matters that started with the name 'Pricing'I would filter on```?law_firm_name__icontains=Pricing```These query would bring back matters called both 'Pricing development contract'and 'Pricing housing development'**Choice filters**Choice filters allow both exact matching and a selection of values to be matched.For example, to search for the single value apple I would include:```?bar=apple```To bring back both apples, pairs and mangos:```?bar__in=apple%2Cpair%2Cmango```Where the field can be null, the `__isnull` filter is provided```?foo__isnull=true```If you want to incorporate null as one of the choices then `__is_null`and `__in` on the same field returns the _union_ of those resources thatmatch one of those values and those resources where this field isn't set:```?foo__isnull=true&foo__in=cucumber%2Ctomato```**Boolean filters**Boolean filters filter out data where a field is true or false. For example, ifI want to bring back matters that I haven't yet shared with the business.```?is_shared=false```