Apperio Filter API

The filter endpoints provide resource discovery in Apperio. This has two 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 metadata that can be filtered, ordered and paginated. Secondly resources may be tagged. The tag management endpoints allow you to create different groupings of matters For those familiar with writing SQL queries, the resource discovery endpoints can be thought of in a similar way. The `SELECT` section or projection clause determines which fields are returned. The `WHERE` clause or filter section determines which records are returned and `ORDER BY` section determines the order that they are returned in. Ordering and pagination is covered in the section above. Below, we will take 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 resource discovery. The client can choose which denormalised fields can appear in the projection clause 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 the endpoint with: ``` ...?fields=one%2Ctwo%2Cthree ``` And the response will bring back only those fields and any mandatory fields (such as the identifier 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 that the user generating the token has access to. This can then be filtered further using explicit filters; resources that the user is not authorized to see will not be returned. **Filtering the data** On the resource discovery endpoints the returning data can be filtered by each of the fields on the resource. Each field has been associated with the type of filter that will make it easier to discover resources. The filter types are explained below. *Range filters* Range filters allow a slice of the data to be selected. They can be used to select all data less than equal to a value; all data above or equal to a value or can be combined to return a slice of the data. For example if I have the field `foo` and wish to return all data between 10000 and 12000 GBP I would add the filters: ``` ?foo__gte=10000&foo__lte=12000 ``` When the field is a monetary field it is assumed that these values will be in your organisation's base currency and any transactions in another currency will be subject to a exchange conversion on the rate held for the date of that transaction. **Text filters** Text filters will return all entries that start with the selected value. For example 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 that match 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, if I want to bring back matters that I haven't yet shared with the business. ``` ?is_shared=false ```