FilterQueryString
Overview
Documentation
Description
This module parses both filter and sorting query string parameters, which allows advanced filtering and sorting in your REST API endpoints. Syntax of query string parameters correspond to the Microsoft API Guidelines as most API guidelines do not specify the syntax of these parameters.
Typical usage scenario
Expose a resource (entity) using the REST publish functionality and give the consumer of the API the possibility to apply filtering and sorting based on the use cases. This prevents re-work in terms of adding new query string parameters every time new attributes are added to the filter functionality.
Features and limitations
Not all operators are supported yet. Grouping and OR operators are not yet implemented. The following operators are supported by the filter query string parameter:
| Operator | Description |
|---|---|
| Comparison operators | |
| eq | Equal |
| ne | Not equal |
| gt | Greater than |
| ge | Greater than or equal |
| lt | Less than |
| le | Less than or equal |
| Logical operators | |
| and | Logical and |
Dependencies
- nl.webflight.filterquerystringparser version 1.0.0
Installation
Add the module to your project. No additional installation required. Use the actions/microflows in the USE_ME folder.
Configuration
- Configure a REST Publish endpoint that exposes a collection (e.g. GET orders or GET customers).
- Add a filter and sorting query string parameter to the endpoint (e.g. filter and orderBy) and map those to the microflow parameters. The filter query string parameter should be in the format filter=description ne ‘test’ and price gt 100 and price lt 200. The sort query string parameter should be in the form orderBy=price desc,description asc or orderBy=id (ascending by default). The syntax is defined in the Microsoft API Guidelines.
- Create a list of FieldNameMapping objects only if field names in your API deviate from the field names in your entity (e.g. orderId to OrderId). By specification of the mapping, the module knows when filtering on a specific field, which attribute to filter on in your database.
- Use the IVK_ParseSortString microflow to translate your sort query string parameter into Sort objects. Apply the same field name mapping if required (use the IVK_MapFieldNamesForSortList).
- Use the ParseFilterQueryString action to translate your query string into an XPath query. Don’t forget to apply exception handling in case the filter query string parameter is invalid. Look into the example IVK_GetOrders to see how exception handling is applied.
- Use the RetrieveObjects or RetrieveObjectCount to get your objects based on the XPath generated in the previous step. Don’t forget to apply exception handling.